Types and Interfaces

/**
 * A set of key-value pairs representing the table entity.
 */
type TableEntity<T extends object = Record<string, unknown>> = T & {
  /** The PartitionKey property of the entity */
  partitionKey: string;
  /** The RowKey property of the entity */
  rowKey: string;
};

/**
 * Output type for query operations with system metadata
 */
type TableEntityResult<T> = T & {
  /** etag property. Always returned by the service */
  etag: string;
  /** Partition key property. Omitted if a select filter is set and this property is not requested */
  partitionKey?: string;
  /** Row key property. Omitted if a select filter is set and this property is not requested */
  rowKey?: string;
  /** Timestamp property. This property is assigned by the service on entity creation. Omitted if a select filter is set and this property is not requested */
  timestamp?: string;
}

/**
 * Supported Entity Data Model types
 */
type EdmTypes = 
  | "Binary" 
  | "Boolean" 
  | "DateTime" 
  | "Double" 
  | "Guid" 
  | "Int32" 
  | "Int64" 
  | "String";

/**
 * Entity Data Model representation for an entity property.
 */
interface Edm<T extends EdmTypes> {
  /** The value of the entity property */
  value: T extends "Binary"
    ? Uint8Array
    : T extends "Boolean"
    ? boolean
    : T extends "Double"
    ? number
    : T extends "Int32"
    ? number
    : string;
  /** The type of the entity property */
  type: T;
}

// Basic entity without explicit EDM types
const basicEntity: TableEntity = {
  partitionKey: "customers",
  rowKey: "customer1", 
  name: "John Doe",
  age: 30,
  isActive: true
};

// Entity with explicit EDM type annotations
const edmEntity: TableEntity = {
  partitionKey: "products",
  rowKey: "product1",
  name: "Laptop",
  price: { value: 999.99, type: "Double" } as Edm<"Double">,
  createDate: { value: new Date(), type: "DateTime" } as Edm<"DateTime">,
  id: { value: "12345678-1234-1234-1234-123456789abc", type: "Guid" } as Edm<"Guid">,
  inventory: { value: "150", type: "Int64" } as Edm<"Int64">
};

// Strongly typed entity with custom interface
interface Customer {
  name: string;
  email: string;
  age: number;
  joinDate: Date;
}

const typedEntity: TableEntity<Customer> = {
  partitionKey: "customers",
  rowKey: "cust001",
  name: "Alice Smith", 
  email: "alice@example.com",
  age: 28,
  joinDate: new Date()
};

/**
 * Represents the Create or Delete Entity operation to be included in a Transaction request
 */
type CreateDeleteEntityAction = ["create" | "delete", TableEntity];

/**
 * Represents the Update or Upsert Entity operation to be included in a Transaction request
 */
type UpdateEntityAction =
  | ["update" | "upsert", TableEntity]
  | ["update" | "upsert", TableEntity, "Merge" | "Replace"];

/**
 * Represents the union of all the available transactional actions
 */
type TransactionAction = CreateDeleteEntityAction | UpdateEntityAction;

/**
 * Update mode for entity modifications
 */
type UpdateMode = "Merge" | "Replace";

/**
 * Response from creating a table entity
 */
interface CreateTableEntityResponse {
  /** Entity tag for the created entity */
  etag: string;
  /** HTTP response metadata */
  _response: HttpResponse;
}

/**
 * Response from retrieving a table entity
 */
interface GetTableEntityResponse<T extends object> {
  /** Entity tag for concurrency control */
  etag: string;
  /** HTTP response metadata */
  _response: HttpResponse;
}

/**
 * Represents the response of a Transaction operation
 */
interface TableTransactionResponse {
  /** Collection of sub responses */
  subResponses: TableTransactionEntityResponse[];
  /** Main Transaction request status code */
  status: number;
  /** Gets a specific response given a row key */
  getResponseForEntity: (rowKey: string) => TableTransactionEntityResponse | undefined;
}

/**
 * Represents a sub-response of a Transaction operation
 */
interface TableTransactionEntityResponse {
  /** Entity's etag */
  etag?: string;
  /** Entity's rowKey */
  rowKey?: string;
  /** Sub-response status */
  status: number;
}

/**
 * Response from access policy operations
 */
interface GetAccessPolicyResponse {
  /** Array of stored access policies */
  signedIdentifiers?: SignedIdentifier[];
  /** HTTP response metadata */
  _response: HttpResponse;
}

interface UpdateEntityResponse {
  /** Entity tag after update */
  etag: string;
  /** HTTP response metadata */
  _response: HttpResponse;
}

interface UpsertEntityResponse {
  /** Entity tag after upsert */
  etag: string;
  /** HTTP response metadata */
  _response: HttpResponse;
}

interface DeleteTableEntityResponse {
  /** HTTP response metadata */
  _response: HttpResponse;
}

interface SetAccessPolicyResponse {
  /** HTTP response metadata */
  _response: HttpResponse;
}

/**
 * Base OData query options for table operations
 */
interface TableQueryOptions {
  /** OData filter expression */
  filter?: string;
  /** Maximum number of entities to return per page */
  top?: number;
}

/**
 * Extended query options with property projection support
 */
interface TableEntityQueryOptions extends TableQueryOptions {
  /** List of properties to include in results (projection) */
  select?: string[];
}

/**
 * Options for listing tables
 */
interface ListTableItemsOptions extends OperationOptions {
  /** Query options for filtering tables */
  queryOptions?: TableQueryOptions;
}

/**
 * Options for listing entities in a table
 */
interface ListTableEntitiesOptions extends OperationOptions {
  /** Query options for filtering and projecting entities */
  queryOptions?: TableEntityQueryOptions;
}

/**
 * Options for retrieving a single entity
 */
interface GetTableEntityOptions extends OperationOptions {
  /** Query options for property projection */
  queryOptions?: TableEntityQueryOptions;
}

/**
 * Options for updating entities
 */
interface UpdateTableEntityOptions extends OperationOptions {
  /** Entity tag for conditional updates */
  etag?: string;
}

/**
 * Options for deleting entities
 */
interface DeleteTableEntityOptions extends OperationOptions {
  /** Entity tag for conditional deletion */
  etag?: string;
}

/**
 * Base operation options available to all API calls
 */
interface OperationOptions {
  /** Callback function for response handling */
  onResponse?: (response: RawResponseCallback) => void;
  /** HTTP request configuration */
  requestOptions?: OperationRequestOptions;
  /** Tracing configuration */
  tracingOptions?: OperationTracingOptions;
  /** Abort signal for operation cancellation */
  abortSignal?: AbortSignalLike;
}

/**
 * Client configuration options
 */
interface TableServiceClientOptions {
  /** Additional HTTP pipeline policies */
  additionalPolicies?: AdditionalPolicyConfig[];
  /** Allow HTTP connections (insecure) */
  allowInsecureConnection?: boolean;
  /** Custom HTTP client implementation */
  httpClient?: HttpClient;
  /** Proxy server configuration */
  proxyOptions?: ProxySettings;
  /** Retry policy settings */
  retryOptions?: PipelineRetryOptions;
  /** Telemetry configuration */
  telemetryOptions?: TelemetryOptions;
  /** User agent policy settings */
  userAgentOptions?: UserAgentPolicyOptions;
}

type TableClientOptions = TableServiceClientOptions;

/**
 * The properties for the table item.
 */
interface TableItem {
  /** The name of the table */
  name?: string;
}

/**
 * Response structure for table queries
 */
interface TableQueryResponse {
  /** Array of matching tables */
  value?: TableItem[];
  /** Continuation token for pagination */
  nextLink?: string;
}

/**
 * Signed access policy identifier
 */
interface SignedIdentifier {
  /** Unique identifier for the policy */
  id: string;
  /** Access policy definition */
  accessPolicy?: AccessPolicy;
}

/**
 * Access policy with permissions and time constraints
 */
interface AccessPolicy {
  /** Policy start time */
  start?: Date;
  /** Policy expiry time */
  expiry?: Date;
  /** Permission string (e.g., "raud" for read/add/update/delete) */
  permission?: string;
}

interface GetStatisticsResponse {
  /** Service replication statistics */
  serviceStats?: TableServiceStats;
  /** HTTP response metadata */
  _response: HttpResponse;
}

interface GetPropertiesResponse {
  /** Current service configuration */
  serviceProperties?: ServiceProperties;
  /** HTTP response metadata */
  _response: HttpResponse;
}

interface SetPropertiesOptions extends OperationOptions {
  /** Request timeout in seconds */
  timeoutInSeconds?: number;
}

interface SetPropertiesResponse {
  /** HTTP response metadata */
  _response: HttpResponse;
}

interface TableServiceStats {
  /** Geo-replication information */
  geoReplication?: GeoReplication;
}

interface GeoReplication {
  /** Current replication status */
  status: GeoReplicationStatusType;
  /** Last successful sync time */
  lastSyncTime?: Date;
}

type GeoReplicationStatusType = "live" | "bootstrap" | "unavailable";

interface ServiceProperties {
  /** Cross-origin resource sharing rules */
  cors?: CorsRule[];
  /** Hourly metrics configuration */
  hourMetrics?: Metrics;
  /** Logging configuration */
  logging?: Logging;
  /** Minute metrics configuration */
  minuteMetrics?: Metrics;
}

interface CorsRule {
  /** Allowed request origins */
  allowedOrigins: string;
  /** Allowed HTTP methods */
  allowedMethods: string;
  /** Allowed request headers */
  allowedHeaders: string;
  /** Headers exposed in responses */
  exposedHeaders: string;
  /** Maximum preflight cache age in seconds */
  maxAgeInSeconds: number;
}

interface Metrics {
  /** Metrics schema version */
  version?: string;
  /** Whether metrics are enabled */
  enabled?: boolean;
  /** Whether to include API call details */
  includeApis?: boolean;
  /** Data retention policy */
  retentionPolicy?: RetentionPolicy;
}

interface Logging {
  /** Logging schema version */
  version?: string;
  /** Log delete operations */
  delete?: boolean;
  /** Log read operations */
  read?: boolean;
  /** Log write operations */
  write?: boolean;
  /** Log data retention policy */
  retentionPolicy?: RetentionPolicy;
}

interface RetentionPolicy {
  /** Whether retention policy is enabled */
  enabled?: boolean;
  /** Number of days to retain data */
  days?: number;
}

interface HttpResponse {
  /** HTTP status code */
  status: number;
  /** Response headers */
  headers: { [key: string]: string };
  /** Response body */
  body?: any;
  /** Request that generated this response */
  request?: any;
}

interface RawResponseCallback {
  /** HTTP response object */
  response: HttpResponse;
}

interface OperationRequestOptions {
  /** Custom request headers */
  customHeaders?: { [key: string]: string };
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Whether to disable automatic response decompression */
  skipUrlEncoding?: boolean;
}

interface OperationTracingOptions {
  /** Tracing namespace */
  tracingContext?: any;
}

interface AdditionalPolicyConfig {
  /** Policy implementation */
  policy: any;
  /** Position in pipeline */
  position: "perCall" | "perRetry";
}

interface ProxySettings {
  /** Proxy server host */
  host: string;
  /** Proxy server port */
  port: number;
  /** Proxy authentication username */
  username?: string;
  /** Proxy authentication password */
  password?: string;
}

interface PipelineRetryOptions {
  /** Maximum number of retry attempts */
  maxRetries?: number;
  /** Initial retry delay in milliseconds */
  retryDelayInMs?: number;
  /** Maximum retry delay in milliseconds */
  maxRetryDelayInMs?: number;
}

interface TelemetryOptions {
  /** Application ID for telemetry */
  applicationId?: string;
  /** Disable telemetry */
  disabled?: boolean;
}

interface UserAgentPolicyOptions {
  /** Additional user agent information */
  userAgentPrefix?: string;
}

interface HttpClient {
  /** Send HTTP request */
  sendRequest: (request: any) => Promise<HttpResponse>;
}

interface AbortSignalLike {
  /** Whether the operation was aborted */
  aborted: boolean;
  /** Event listener for abort events */
  addEventListener: (type: "abort", listener: () => void) => void;
}

import { TableClient, AzureNamedKeyCredential } from "@azure/data-tables";

// Using custom entity types
interface Product {
  name: string;
  price: number;
  category: string;
  inStock: boolean;
  lastUpdated: Date;
}

const tableClient = new TableClient(
  "https://myaccount.table.core.windows.net",
  "Products", 
  new AzureNamedKeyCredential("account", "key")
);

// Strongly typed entity operations
const product: TableEntity<Product> = {
  partitionKey: "electronics",
  rowKey: "laptop-001",
  name: "Gaming Laptop",
  price: 1299.99,
  category: "computers",
  inStock: true,
  lastUpdated: new Date()
};

await tableClient.createEntity(product);

// Type-safe querying with options
const expensiveProducts = tableClient.listEntities<Product>({
  queryOptions: {
    filter: "price gt 1000",
    select: ["name", "price", "category"],
    top: 50
  }
});

for await (const product of expensiveProducts) {
  // product is typed as TableEntityResult<Product>
  console.log(`${product.name}: $${product.price}`);
  console.log(`ETag: ${product.etag}, Modified: ${product.timestamp}`);
}