Table Client

/**
 * A client for performing operations on a single Azure table, including entity CRUD operations and transactions.
 */
class TableClient {
  /** Table Account URL */
  readonly url: string;
  /** HTTP request pipeline */
  readonly pipeline: Pipeline;
  /** Name of the table */
  readonly tableName: string;

  /** Create with Named Key credential */
  constructor(url: string, tableName: string, credential: NamedKeyCredential, options?: TableClientOptions);
  /** Create with SAS credential */
  constructor(url: string, tableName: string, credential: SASCredential, options?: TableClientOptions);
  /** Create with Token credential */
  constructor(url: string, tableName: string, credential: TokenCredential, options?: TableClientOptions);
  /** Create with anonymous access */
  constructor(url: string, tableName: string, options?: TableClientOptions);

  /** Create client from connection string */
  static fromConnectionString(connectionString: string, tableName: string, options?: TableClientOptions): TableClient;
}

interface TableClientOptions extends CommonClientOptions {
  /** Service endpoint URL */
  endpoint?: string;
  /** API version to use */
  version?: string;
}

/**
 * Creates the table if it doesn't already exist
 * @param options - Optional parameters for the operation
 */
createTable(options?: OperationOptions): Promise<void>;

/**
 * Deletes the table and all data within it
 * @param options - Optional parameters for the operation
 */
deleteTable(options?: OperationOptions): Promise<void>;

/**
 * Creates a new entity in the table
 * @param entity - The entity to create, must include partitionKey and rowKey
 * @param options - Optional parameters for the operation
 * @returns Response with entity metadata
 */
createEntity<T extends object>(entity: TableEntity<T>, options?: OperationOptions): Promise<CreateTableEntityResponse>;

/**
 * Retrieves a single entity by partition and row key
 * @param partitionKey - The partition key of the entity
 * @param rowKey - The row key of the entity
 * @param options - Optional parameters including select projection
 * @returns The entity with metadata
 */
getEntity<T extends object>(
  partitionKey: string, 
  rowKey: string, 
  options?: GetTableEntityOptions
): Promise<GetTableEntityResponse<TableEntityResult<T>>>;

/**
 * Updates an existing entity in the table
 * @param entity - The entity to update, must include partitionKey, rowKey, and etag
 * @param mode - Update mode: "Merge" (partial) or "Replace" (full)
 * @param options - Optional parameters for the operation
 * @returns Response with updated entity metadata
 */
updateEntity<T extends object>(
  entity: TableEntity<T>, 
  mode?: UpdateMode, 
  options?: UpdateTableEntityOptions
): Promise<UpdateEntityResponse>;

/**
 * Creates an entity if it doesn't exist, or updates/replaces if it does
 * @param entity - The entity to upsert, must include partitionKey and rowKey
 * @param mode - Update mode: "Merge" (partial) or "Replace" (full) for existing entities
 * @param options - Optional parameters for the operation
 * @returns Response with entity metadata
 */
upsertEntity<T extends object>(
  entity: TableEntity<T>, 
  mode?: UpdateMode, 
  options?: OperationOptions
): Promise<UpsertEntityResponse>;

/**
 * Deletes an entity from the table
 * @param partitionKey - The partition key of the entity to delete
 * @param rowKey - The row key of the entity to delete
 * @param options - Optional parameters including etag for conditional deletion
 * @returns Response confirming deletion
 */
deleteEntity(
  partitionKey: string, 
  rowKey: string, 
  options?: DeleteTableEntityOptions
): Promise<DeleteTableEntityResponse>;

/**
 * Lists entities in the table with optional filtering and pagination
 * @param options - Optional parameters for querying including OData filters
 * @returns Pageable iterator of entities
 */
listEntities<T extends object>(options?: ListTableEntitiesOptions): PagedAsyncIterableIterator<TableEntityResult<T>, TableEntityResult<T>[]>;

interface CreateTableEntityResponse {
  /** Entity metadata */
  etag: string;
  /** Response headers */
  _response: HttpResponse;
}

interface GetTableEntityResponse<T extends object> {
  /** Entity metadata */
  etag: string;
  /** Response headers */
  _response: HttpResponse;
}

interface UpdateEntityResponse {
  /** Entity metadata */
  etag: string;
  /** Response headers */
  _response: HttpResponse;
}

interface UpsertEntityResponse {
  /** Entity metadata */
  etag: string;
  /** Response headers */
  _response: HttpResponse;
}

interface DeleteTableEntityResponse {
  /** Response headers */
  _response: HttpResponse;
}

interface GetTableEntityOptions extends OperationOptions {
  /** List of properties to select */
  queryOptions?: TableEntityQueryOptions;
}

interface ListTableEntitiesOptions extends OperationOptions {
  /** OData query options for filtering and pagination */
  queryOptions?: TableEntityQueryOptions;
}

interface UpdateTableEntityOptions extends OperationOptions {
  /** ETag for conditional updates */
  etag?: string;
}

interface DeleteTableEntityOptions extends OperationOptions {
  /** ETag for conditional deletion */
  etag?: string;
}

interface TableEntityQueryOptions extends TableQueryOptions {
  /** List of properties to select (projection) */
  select?: string[];
}

interface TableQueryOptions {
  /** OData filter expression */
  filter?: string;
  /** Maximum number of entities to return per page */
  top?: number;
}

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

const credential = new AzureNamedKeyCredential("accountName", "accountKey");
const tableClient = new TableClient("https://myaccount.table.core.windows.net", "Customers", credential);

// Create table if it doesn't exist
await tableClient.createTable();

// Create an entity
const customer = {
  partitionKey: "Customers",
  rowKey: "customer1",
  name: "John Doe",
  email: "john@example.com",
  age: 30,
  isActive: true
};

const createResponse = await tableClient.createEntity(customer);
console.log(`Created entity with etag: ${createResponse.etag}`);

// Get a specific entity
const entity = await tableClient.getEntity("Customers", "customer1");
console.log(`Retrieved: ${entity.name} (${entity.email})`);

// Update an entity (merge)
await tableClient.updateEntity({
  partitionKey: "Customers",
  rowKey: "customer1", 
  etag: entity.etag,
  age: 31
}, "Merge");

// Upsert an entity (create or replace)
await tableClient.upsertEntity({
  partitionKey: "Customers",
  rowKey: "customer2",
  name: "Jane Smith",
  email: "jane@example.com",
  age: 25
}, "Replace");

// Query entities with filtering
const activeCustomers = tableClient.listEntities({
  queryOptions: {
    filter: odata`isActive eq true and age gt 25`,
    select: ["name", "email", "age"]
  }
});

for await (const customer of activeCustomers) {
  console.log(`Active customer: ${customer.name}`);
}

// Delete an entity
await tableClient.deleteEntity("Customers", "customer1");

/**
 * Gets the stored access policies for the table
 * @param options - Optional parameters for the operation
 * @returns Current access policies
 */
getAccessPolicy(options?: OperationOptions): Promise<GetAccessPolicyResponse>;

/**
 * Sets the stored access policies for the table
 * @param tableAcl - Array of signed identifiers with access policies
 * @param options - Optional parameters for the operation
 * @returns Response confirming policy update
 */
setAccessPolicy(tableAcl: SignedIdentifier[], options?: OperationOptions): Promise<SetAccessPolicyResponse>;

interface GetAccessPolicyResponse {
  /** Array of signed identifiers */
  signedIdentifiers?: SignedIdentifier[];
  /** Response headers */
  _response: HttpResponse;
}

interface SetAccessPolicyResponse {
  /** Response headers */
  _response: HttpResponse;
}

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

interface AccessPolicy {
  /** Policy start time */
  start?: Date;
  /** Policy expiry time */
  expiry?: Date;
  /** Permissions granted by the policy */
  permission?: string;
}

// Get current access policies
const policies = await tableClient.getAccessPolicy();
console.log("Current policies:", policies.signedIdentifiers);

// Set new access policies
await tableClient.setAccessPolicy([
  {
    id: "read-only-policy",
    accessPolicy: {
      start: new Date(),
      expiry: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
      permission: "r" // Read-only
    }
  },
  {
    id: "full-access-policy", 
    accessPolicy: {
      start: new Date(),
      expiry: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
      permission: "raud" // Read, Add, Update, Delete
    }
  }
]);

/**
 * Submits a transaction with multiple operations within the same partition
 * @param actions - Array of transaction actions to perform atomically
 * @returns Response with results for each action
 */
submitTransaction(actions: TransactionAction[]): Promise<TableTransactionResponse>;

interface TableTransactionResponse {
  /** Status of the transaction */
  status: number;
  /** Array of sub-responses for each action */
  subResponses: TableTransactionEntityResponse[];
  /** Response headers */
  _response: HttpResponse;
}

interface TableTransactionEntityResponse {
  /** Status code for this action */
  status: number;
  /** Entity returned by the action (for creates/updates) */
  entity?: any;
  /** Error information if action failed */
  error?: any;
  /** Response headers for this action */
  headers: { [key: string]: string };
}

import { TableTransaction } from "@azure/data-tables";

// Build transaction with helper class
const transaction = new TableTransaction();
transaction.createEntity({ partitionKey: "Batch", rowKey: "1", name: "Entity 1" });
transaction.updateEntity({ partitionKey: "Batch", rowKey: "2", name: "Updated Entity" });
transaction.deleteEntity("Batch", "3");

// Submit the transaction
const result = await tableClient.submitTransaction(transaction.actions);
console.log(`Transaction completed with status: ${result.status}`);

// Check individual action results
result.subResponses.forEach((response, index) => {
  console.log(`Action ${index}: ${response.status}`);
});

interface OperationOptions {
  /** A function to be called each time a response is received from the server */
  onResponse?: (response: RawResponseCallback) => void;
  /** Options used when creating and sending HTTP requests */
  requestOptions?: OperationRequestOptions;
  /** Options used when tracing is enabled */
  tracingOptions?: OperationTracingOptions;
  /** Abort signal for canceling the operation */
  abortSignal?: AbortSignalLike;
}

type NamedKeyCredential = AzureNamedKeyCredential;
type SASCredential = AzureSASCredential;
type UpdateMode = "Merge" | "Replace";

// From @azure/core-client
interface CommonClientOptions {
  /** Additional policies to add to the pipeline */
  additionalPolicies?: AdditionalPolicyConfig[];
  /** Allow insecure connections when using HTTP */
  allowInsecureConnection?: boolean;
  /** HTTP client implementation */
  httpClient?: HttpClient;
  /** Proxy configuration */
  proxyOptions?: ProxySettings;
  /** Retry policy configuration */
  retryOptions?: PipelineRetryOptions;
  /** Telemetry options */
  telemetryOptions?: TelemetryOptions;
  /** User agent policy configuration */
  userAgentOptions?: UserAgentPolicyOptions;
}