@esposter/azure

It holds the Azure wire conventions that a real client and a fake client must both follow. They are the OData filter clause vocabulary shared by Table Storage and Search, the entity key casing convention and the service limits.

Design notes live in the specs.

Table of Contents

• 🚀 Getting Started
• 🧩 Key Exports
• ⚖️ License

🚀 Getting Started

Install the package:

pnpm add @esposter/azure

🧩 Key Exports

Clauses

A Clause<T> is a filter condition on a property of T. The OData string is built from clauses. Do not assemble the string by hand.

• BinaryOperator holds the comparisons that Table Storage understands.
• SearchOperator holds the collection predicates that only Azure Search supports.
• UnaryOperator combines clauses.

import type { Clause } from "@esposter/azure";

import { BinaryOperator } from "@esposter/azure";

const clause: Clause<{ createdAt: Date }> = { key: "createdAt", operator: BinaryOperator.Ge, value: new Date(0) };

Values

serializeValue renders a SerializableValue in the format that the target service expects. isTableFilter selects the format.

• Table Storage: a Date renders as a datetime'<iso>' literal.
• Search: a Date renders as the bare ISO string.

Strings go through escapeValue. It doubles each embedded single quote, so a value cannot close its own literal or add filter syntax of its own.

import { escapeValue, serializeValue } from "@esposter/azure";

Filters

serializeClauses turns a clause array into a Table Storage filter string. serializeSearchClauses turns a clause array into a Search filter string. The two differ only in how a Date renders.

Clauses on the same key are grouped:

• A range pair is joined with and.
• Any other group is joined with or.

Do not assemble the boolean structure by hand. deserializeClause is the inverse.

import { BinaryOperator, CompositeKeyPropertyNames, getTableNullClause, serializeClauses } from "@esposter/azure";

const roomId = crypto.randomUUID();
const filter = serializeClauses([
  { key: CompositeKeyPropertyNames.partitionKey, operator: BinaryOperator.Eq, value: roomId },
  getTableNullClause("deletedAt"),
]);

The two services handle null differently. The helpers handle the difference.

• getTableNullClause expresses "is null" for Table Storage.
• Search supports null directly, through getSearchNullClause / getSearchNonNullClause.

getPartitionKeyFilter builds the one-clause filter that selects everything under one partition key. A read, a count and a purge of the same entity must all start from this filter.

Keys

CompositeKey is the partitionKey/rowKey pair that every Table entity carries. Refer to these names through CompositeKeyPropertyNames. Do not restate the strings. serializeKey and deserializeKey convert keys at the boundary.

import { CompositeKey, CompositeKeyPropertyNames, serializeKey } from "@esposter/azure";

Limits

These constants hold the maximum values that the service allows: AZURE_MAX_BATCH_SIZE, AZURE_MAX_PAGE_SIZE and AZURE_MAX_QUEUE_VISIBILITY_TIMEOUT_MS. Use them when you paginate, batch or enqueue. Do not hard-code these values.

⚖️ License

This project is licensed under the Apache-2.0 license.