@esposter/azure 4.3.3 → 4.4.0

package/README.md

@@ -5,15 +5,14 @@
 [![NPM downloads][badge-npm-downloads]][url-npm]
 [![NPM Unpacked Size (with version)][badge-npm-unpacked-size]][url-npm]
 
-The parts of Azure's wire contract that both a real client and a fake one have to agree on: the OData filter
-clause vocabulary shared by Table Storage and Search, the entity key casing convention, and the service limits.
-No SDK client is constructed here and no credential is read — this package is pure data and pure functions, so
-it runs anywhere.
+The Azure wire conventions that a real client and a fake one both have to speak: 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](https://github.com/Esposter/Esposter/tree/main/openspec/specs).
 
 ## Table of Contents
 
 - 🚀 [Getting Started](#getting-started)
-- 📖 [Documentation](#documentation)
+- 🧩 [Key Exports](#key-exports)
 - ⚖️ [License](#license)
 
 ---
@@ -24,9 +23,22 @@ it runs anywhere.
 pnpm add @esposter/azure
 ```
 
-## <a name="documentation">📖 Documentation</a>
-
-We highly recommend you take a look at the [documentation](https://github.com/Esposter/Esposter/tree/main/openspec/specs) to level up.
+## <a name="key-exports">🧩 Key Exports</a>
+
+| Export                      | Kind     | Purpose                                                                      |
+| --------------------------- | -------- | ---------------------------------------------------------------------------- |
+| `AZURE_MAX_PAGE_SIZE`       | const    | Largest page size the service returns in one call                            |
+| `BinaryOperator`            | enum     | Comparison operators Table Storage understands                               |
+| `Clause`                    | type     | A filter condition on one property, the unit OData strings are built from    |
+| `CompositeKey`              | class    | The `partitionKey` and `rowKey` pair every Table entity carries              |
+| `CompositeKeyPropertyNames` | const    | The `CompositeKey` property names, so callers never restate the strings      |
+| `deserializeClause`         | function | Parses a serialized filter clause back into a `Clause`, throwing on no match |
+| `escapeValue`               | function | Quotes a string as an OData literal, doubling embedded single quotes         |
+| `getPartitionKeyFilter`     | function | The filter selecting everything under one partition key                      |
+| `getTableNullClause`        | function | The Table Storage "is null" clause, a negated `NaN` comparison               |
+| `SearchOperator`            | enum     | Collection predicates only Azure Search supports                             |
+| `serializeClauses`          | function | Serializes clauses into a Table Storage OData filter string                  |
+| `serializeValue`            | function | Renders one `SerializableValue` as a literal for Table or Search             |
 
 ### Clauses
 
@@ -57,10 +69,9 @@ import { escapeValue, serializeValue } from "@esposter/azure";
 ### Filters
 
 `serializeClauses` turns a clause array into a Table Storage filter string and `serializeSearchClauses` into a
-Search one; the two differ only in how a `Date` renders, which is why they share a single core. Clauses on the
-same key are grouped — a range pair is joined with `and`, anything else with `or` — so a caller never assembles
-the boolean structure by hand. `deserializeClause` is the inverse, and is what lets a fake client evaluate a
-filter it was handed rather than pattern-matching the string.
+Search one; the two differ only in how a `Date` renders. Clauses on the same key are grouped — a range pair is
+joined with `and`, anything else with `or` — so a caller never assembles the boolean structure by hand.
+`deserializeClause` is the inverse.
 
 ```ts
 import { BinaryOperator, CompositeKeyPropertyNames, getTableNullClause, serializeClauses } from "@esposter/azure";
@@ -72,17 +83,13 @@ const filter = serializeClauses([
 ]);
 ```
 
-Null is where the two services diverge and the helpers carry the difference: Table Storage cannot compare
-against null at all, so `getTableNullClause` expresses "is null" as a negated `NaN` comparison, while Search
-supports it directly through `getSearchNullClause` / `getSearchNonNullClause`. `getPartitionKeyFilter` is the
-one-clause case worth naming, since a read, a count and a purge of the same entity must all start from it.
+Null is where the two services diverge and the helpers carry the difference: `getTableNullClause` expresses "is null" for Table Storage, while Search supports it directly through `getSearchNullClause` / `getSearchNonNullClause`. `getPartitionKeyFilter` is the one-clause case worth naming, since a read, a count and a purge of the same entity must all start from it.
 
 ### Keys
 
 `CompositeKey` is the `partitionKey`/`rowKey` pair every Table entity carries, and `CompositeKeyPropertyNames`
-is how those names are referred to without restating the strings. The wire spells those two capitalized and
-JavaScript does not, so `serializeKey` and `deserializeKey` convert at the boundary and nothing in between has
-to know.
+is how those names are referred to without restating the strings. `serializeKey` and `deserializeKey` convert
+at the boundary.
 
 ```ts
 import { CompositeKey, CompositeKeyPropertyNames, serializeKey } from "@esposter/azure";
@@ -93,17 +100,6 @@ import { CompositeKey, CompositeKeyPropertyNames, serializeKey } from "@esposter
 `AZURE_MAX_BATCH_SIZE`, `AZURE_MAX_PAGE_SIZE` and `AZURE_MAX_QUEUE_VISIBILITY_TIMEOUT_MS` are the service's own
 ceilings, named so a caller paginating, batching or enqueueing does not hard-code them.
 
-### Commands
-
-Run from `packages/azure/`:
-
-```bash
-pnpm build        # compile to dist/
-pnpm test         # vitest watch mode (coverage is run from the repo root)
-pnpm lint:fix     # auto-fix lint
-pnpm typecheck    # type check
-```
-
 ## <a name="license">⚖️ License</a>
 
 This project is licensed under the [Apache-2.0 license](https://github.com/Esposter/Esposter/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esposter/azure",
-  "version": "4.3.3",
+  "version": "4.4.0",
   "description": "The Azure wire conventions Esposter's clients and its mocks both speak — OData filter clauses, entity key casing, and service limits.",
   "keywords": [
     "azure",
@@ -41,14 +41,14 @@
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "test": "vitest",
-    "typecheck": "tsc"
+    "typecheck": "tsrs --fast"
   },
   "dependencies": {
-    "@esposter/shared": "4.3.3"
+    "@esposter/shared": "4.4.0"
   },
   "devDependencies": {
-    "@esposter/configuration": "4.3.3",
-    "tsdown": "^0.23.1",
+    "@esposter/configuration": "4.4.0",
+    "tsdown": "0.23.2",
     "type-fest": "^5.10.0"
   },
   "peerDependencies": {
@@ -58,5 +58,5 @@
   "inlinedDependencies": {
     "type-fest": "5.10.0"
   },
-  "gitHead": "955bbc130ad9b28877fd4ae8efc73a045141ce01"
+  "gitHead": "e1a416c4b91da69cc2aa259b50a4d656f204d272"
 }

package/dist/index.d.ts

@@ -1,159 +0,0 @@
-import { z } from "zod";
-import { PropertyNames } from "@esposter/shared";
-import { TableEntity } from "@azure/data-tables";
-export declare enum SearchOperator {
-  ArrayAny = "arrayAny",
-  ArrayContains = "arrayContains"
-}
-export declare enum BinaryOperator {
-  Eq = "eq",
-  Ge = "ge",
-  Gt = "gt",
-  Le = "le",
-  Lt = "lt",
-  Ne = "ne"
-}
-export declare const BinaryOperators: readonly BinaryOperator[];
-export type SerializableValue = boolean | Date | null | number | string;
-export declare const serializableValueSchema: z.ZodType<SerializableValue, SerializableValue>;
-export type Clause<T extends object> = {
-  key: keyof T & string;
-  not?: boolean;
-} & ({
-  operator: BinaryOperator;
-  value: SerializableValue;
-} | {
-  operator: SearchOperator.ArrayAny;
-} | {
-  operator: SearchOperator.ArrayContains;
-  value: SerializableValue[];
-});
-export declare enum UnaryOperator {
-  And = "and",
-  Not = "not",
-  Or = "or"
-}
-/**
-Omit any index signatures from the given object type, leaving only explicitly defined properties.
-
-This is the counterpart of `PickIndexSignature`.
-
-Use-cases:
-- Remove overly permissive signatures from third-party types.
-
-This type was taken from this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).
-
-It relies on the fact that an empty object (`{}`) is assignable to an object with just an index signature, like `Record<string, unknown>`, but not to an object with explicitly defined keys, like `Record<'foo' | 'bar', unknown>`.
-
-(The actual value type, `unknown`, is irrelevant and could be any type. Only the key type matters.)
-
-```
-const indexed: Record<string, unknown> = {}; // Allowed
-
-// @ts-expect-error
-const keyed: Record<'foo', unknown> = {}; // Error
-// TS2739: Type '{}' is missing the following properties from type 'Record<"foo" | "bar", unknown>': foo, bar
-```
-
-Instead of causing a type error like the above, you can also use a [conditional type](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html) to test whether a type is assignable to another:
-
-```
-type Indexed = {} extends Record<string, unknown>
-	? '✅ `{}` is assignable to `Record<string, unknown>`'
-	: '❌ `{}` is NOT assignable to `Record<string, unknown>`';
-
-type IndexedResult = Indexed;
-//=> '✅ `{}` is assignable to `Record<string, unknown>`'
-
-type Keyed = {} extends Record<'foo' | 'bar', unknown>
-	? '✅ `{}` is assignable to `Record<\'foo\' | \'bar\', unknown>`'
-	: '❌ `{}` is NOT assignable to `Record<\'foo\' | \'bar\', unknown>`';
-
-type KeyedResult = Keyed;
-//=> '❌ `{}` is NOT assignable to `Record<\'foo\' | \'bar\', unknown>`'
-```
-
-Using a [mapped type](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#further-exploration), you can then check for each `KeyType` of `ObjectType`...
-
-```
-type OmitIndexSignature<ObjectType> = {
-	[KeyType in keyof ObjectType // Map each key of `ObjectType`...
-	]: ObjectType[KeyType]; // ...to its original value, i.e. `OmitIndexSignature<Foo> == Foo`.
-};
-```
-
-...whether an empty object (`{}`) would be assignable to an object with that `KeyType` (`Record<KeyType, unknown>`)...
-
-```
-type OmitIndexSignature<ObjectType> = {
-	[KeyType in keyof ObjectType
-	// Is `{}` assignable to `Record<KeyType, unknown>`?
-	as {} extends Record<KeyType, unknown>
-		? never // ✅ `{}` is assignable to `Record<KeyType, unknown>`
-		: KeyType // ❌ `{}` is NOT assignable to `Record<KeyType, unknown>`
-	]: ObjectType[KeyType];
-};
-```
-
-If `{}` is assignable, it means that `KeyType` is an index signature and we want to remove it. If it is not assignable, `KeyType` is a "real" key and we want to keep it.
-
-@example
-```
-import type {OmitIndexSignature} from 'type-fest';
-
-type Example = {
-	// These index signatures will be removed.
-	[x: string]: any;
-	[x: number]: any;
-	[x: symbol]: any;
-	[x: `head-${string}`]: string;
-	[x: `${string}-tail`]: string;
-	[x: `head-${string}-tail`]: string;
-	[x: `${bigint}`]: string;
-	[x: `embedded-${number}`]: string;
-
-	// These explicitly defined keys will remain.
-	foo: 'bar';
-	qux?: 'baz';
-};
-
-type ExampleWithoutIndexSignatures = OmitIndexSignature<Example>;
-//=> {foo: 'bar'; qux?: 'baz'}
-```
-
-@see {@link PickIndexSignature}
-@category Object
-*/
-type OmitIndexSignature<ObjectType> = { [KeyType in keyof ObjectType as {} extends Record<KeyType, unknown> ? never : KeyType]: ObjectType[KeyType]; };
-export declare class CompositeKey implements OmitIndexSignature<TableEntity> {
-  partitionKey: string;
-  rowKey: string;
-}
-export declare const CompositeKeyPropertyNames: PropertyNames<CompositeKey>;
-export declare const getSearchNonNullClause: <T extends object>(key: keyof T & string) => Clause<T>;
-export declare const getSearchNullClause: <T extends object>(key: keyof T & string) => Clause<T>;
-export declare const AZURE_MAX_BATCH_SIZE = 100;
-export declare const AZURE_MAX_PAGE_SIZE = 1e3;
-export declare const SERIALIZABLE_VALUE_MAX_LENGTH = 100;
-export declare const AZURE_MAX_QUEUE_VISIBILITY_TIMEOUT_MS: number;
-export declare const AZURE_MAX_STRING_PROPERTY_LENGTH: number;
-export declare const KEYS_TO_CAPITALIZE: ReadonlySet<string>;
-export declare const KEYS_TO_UNCAPITALIZE: ReadonlySet<string>;
-export declare const deserializeKey: (key: string) => string;
-export declare const getTableNullClause: <T extends object>(key: keyof T & string) => Clause<T>;
-export declare const serializeKey: (key: string) => string;
-export declare const RangeOperators: (BinaryOperator | SearchOperator)[];
-export declare const DATETIME_LITERAL_PREFIX = "datetime'";
-export declare const CLAUSE_REGEX: RegExp;
-export declare const deserializeClause: (serializedClause: string) => Extract<Clause<Record<string, unknown>>, {
-  operator: BinaryOperator;
-}>;
-export declare const deserializeValue: (serializedValue: string) => SerializableValue;
-export declare const escapeValue: (value: string) => string;
-export declare const getPartitionKeyFilter: (partitionKey: CompositeKey["partitionKey"]) => string;
-export declare const serializeClause: (clause: Clause<Record<string, unknown>>, isTableFilter?: boolean) => string;
-export declare const serializeClauses: (clauses: Clause<Record<string, unknown>>[]) => string;
-export declare const serializeClausesCore: (clauses: Clause<Record<string, unknown>>[], isTableFilter: boolean) => string;
-export declare const serializeSearchClauses: (clauses: Clause<Record<string, unknown>>[]) => string;
-export declare const serializeValue: (value: SerializableValue, isTableFilter?: boolean) => string;
-export {};

package/dist/index.js

@@ -1,167 +0,0 @@
-import { z } from "zod";
-import { InvalidOperationError, NotFoundError, Operation, capitalize, getPropertyNames, getResult, normalizeString, takeOne, uncapitalize } from "@esposter/shared";
-// src/models/search/SearchOperator.ts
-let SearchOperator = /* @__PURE__ */ function(SearchOperator) {
-	SearchOperator["ArrayAny"] = "arrayAny";
-	SearchOperator["ArrayContains"] = "arrayContains";
-	return SearchOperator;
-}({});
-// src/models/shared/BinaryOperator.ts
-let BinaryOperator = /* @__PURE__ */ function(BinaryOperator) {
-	BinaryOperator["Eq"] = "eq";
-	BinaryOperator["Ge"] = "ge";
-	BinaryOperator["Gt"] = "gt";
-	BinaryOperator["Le"] = "le";
-	BinaryOperator["Lt"] = "lt";
-	BinaryOperator["Ne"] = "ne";
-	return BinaryOperator;
-}({});
-const BinaryOperators = Object.values(BinaryOperator);
-// src/services/shared/constants.ts
-const AZURE_MAX_BATCH_SIZE = 100;
-const AZURE_MAX_PAGE_SIZE = 1e3;
-const SERIALIZABLE_VALUE_MAX_LENGTH = 100;
-const AZURE_MAX_QUEUE_VISIBILITY_TIMEOUT_MS = Temporal.Duration.from({ days: 7 }).total("milliseconds");
-const AZURE_MAX_STRING_PROPERTY_LENGTH = 32768;
-// src/models/shared/SerializableValue.ts
-const serializableValueSchema = z.union([
-	z.boolean(),
-	z.date(),
-	z.null(),
-	z.number(),
-	z.string().min(1).max(100)
-]);
-// src/models/shared/UnaryOperator.ts
-let UnaryOperator = /* @__PURE__ */ function(UnaryOperator) {
-	UnaryOperator["And"] = "and";
-	UnaryOperator["Not"] = "not";
-	UnaryOperator["Or"] = "or";
-	return UnaryOperator;
-}({});
-// src/models/table/CompositeKey.ts
-var CompositeKey = class {};
-const CompositeKeyPropertyNames = getPropertyNames();
-// src/services/search/getSearchNonNullClause.ts
-const getSearchNonNullClause = (key) => ({
-	key,
-	operator: "ne",
-	value: null
-});
-// src/services/search/getSearchNullClause.ts
-const getSearchNullClause = (key) => ({
-	key,
-	operator: "eq",
-	value: null
-});
-// src/services/table/constants.ts
-const KEYS_TO_CAPITALIZE = /* @__PURE__ */ new Set([CompositeKeyPropertyNames.partitionKey, CompositeKeyPropertyNames.rowKey]);
-const KEYS_TO_UNCAPITALIZE = /* @__PURE__ */ new Set([capitalize(CompositeKeyPropertyNames.partitionKey), capitalize(CompositeKeyPropertyNames.rowKey)]);
-// src/services/table/deserializeKey.ts
-const deserializeKey = (key) => KEYS_TO_UNCAPITALIZE.has(key) ? uncapitalize(key) : key;
-// src/services/table/getTableNullClause.ts
-const getTableNullClause = (key) => ({
-	key,
-	not: true,
-	operator: "ne",
-	value: NaN
-});
-// src/services/table/serializeKey.ts
-const serializeKey = (key) => KEYS_TO_CAPITALIZE.has(key) ? capitalize(key) : key;
-// src/services/transformer/RangeOperators.ts
-const RangeOperators = [
-	"ge",
-	"gt",
-	"le",
-	"lt"
-];
-// src/services/transformer/constants.ts
-const DATETIME_LITERAL_PREFIX = "datetime'";
-const VALUE_REGEX = [
-	true,
-	false,
-	String.raw`${DATETIME_LITERAL_PREFIX}[^']*'`,
-	String.raw`\d{4}-\d{2}-\d{2}T[^\s]+`,
-	String(null),
-	String.raw`-?\d+(?:\.\d+)?`,
-	String(NaN),
-	"'(?:[^']|'')*'"
-].join("|");
-const CLAUSE_REGEX = new RegExp(String.raw`^(?<not>not\s+)?(?<key>[A-Za-z0-9_]*)\s*(?<operator>${BinaryOperators.join("|")})\s+(?<value>${VALUE_REGEX})$`, "iu");
-// src/services/transformer/deserializeValue.ts
-const parseIsoDate = (isoValue) => getResult(() => new Date(Temporal.Instant.from(isoValue).epochMilliseconds)).unwrapOr(void 0);
-const deserializeValue = (serializedValue) => {
-	if (serializedValue === String(true)) return true;
-	else if (serializedValue === String(false)) return false;
-	else if (serializedValue === String(null)) return null;
-	else if (Number.isFinite(Number(serializedValue))) return Number(serializedValue);
-	else if (serializedValue === String(NaN)) return NaN;
-	else if (serializedValue.startsWith("datetime'") && serializedValue.endsWith("'")) return parseIsoDate(serializedValue.slice(9, -1)) ?? serializedValue;
-	else if (serializedValue.startsWith("'") && serializedValue.endsWith("'")) return serializedValue.slice(1, -1).replaceAll("''", "'");
-	else return parseIsoDate(serializedValue) ?? serializedValue;
-};
-// src/services/transformer/deserializeClause.ts
-const deserializeClause = (serializedClause) => {
-	const normalizedClause = normalizeString(serializedClause);
-	const match = CLAUSE_REGEX.exec(normalizedClause);
-	if (!match) throw new NotFoundError(deserializeClause.name, normalizedClause);
-	const groups = match.groups;
-	if (!groups) throw new NotFoundError(deserializeClause.name, normalizedClause);
-	return {
-		key: deserializeKey(groups.key),
-		not: Boolean(groups.not),
-		operator: groups.operator.toLowerCase(),
-		value: deserializeValue(groups.value)
-	};
-};
-// src/services/transformer/escapeValue.ts
-const escapeValue = (value) => `'${value.replaceAll("'", "''")}'`;
-// src/services/transformer/serializeValue.ts
-const serializeValue = (value, isTableFilter = false) => {
-	if (value instanceof Date) return isTableFilter ? `${DATETIME_LITERAL_PREFIX}${value.toISOString()}'` : value.toISOString();
-	else if (typeof value === "string") return escapeValue(value);
-	else return String(value);
-};
-// src/services/transformer/serializeClause.ts
-const serializeClause = (clause, isTableFilter = false) => {
-	const keys = clause.key.split("/").map((key) => serializeKey(key));
-	const clauseKey = keys.join("/");
-	if (clause.operator === "arrayAny") return `${clauseKey}/any()`;
-	else if (clause.operator === "arrayContains") {
-		const serializedValue = serializeValue(clause.value.join(","));
-		if (keys.length === 1) return `${clauseKey}/any(x: search.in(x, ${serializedValue}))`;
-		else if (keys.length === 2) {
-			const [collectionName, propertyName] = keys;
-			return `${collectionName}/any(x: search.in(x/${propertyName}, ${serializedValue}))`;
-		} else throw new InvalidOperationError(Operation.Read, serializeClause.name, clause.key);
-	}
-	const { not, operator, value } = clause;
-	const baseClause = `${clauseKey} ${operator} ${serializeValue(value, isTableFilter)}`;
-	return not ? `not(${baseClause})` : baseClause;
-};
-// src/services/transformer/serializeClausesCore.ts
-const serializeClausesCore = (clauses, isTableFilter) => {
-	if (clauses.length === 0) return "";
-	else if (clauses.length === 1) return serializeClause(takeOne(clauses), isTableFilter);
-	else {
-		const groupedClauses = Object.groupBy(clauses, ({ key }) => key);
-		const groupedStrings = [];
-		for (const clauseGroup of Object.values(groupedClauses)) if (clauseGroup.length === 1) groupedStrings.push(serializeClause(takeOne(clauseGroup), isTableFilter));
-		else {
-			const serializedClauses = clauseGroup.map((clause) => serializeClause(clause, isTableFilter));
-			const groupedString = clauseGroup.some(({ operator }) => RangeOperators.includes(operator)) ? serializedClauses.join(` and `) : `(${serializedClauses.join(` or `)})`;
-			groupedStrings.push(groupedString);
-		}
-		return groupedStrings.join(` and `);
-	}
-};
-// src/services/transformer/serializeClauses.ts
-const serializeClauses = (clauses) => serializeClausesCore(clauses, true);
-// src/services/transformer/getPartitionKeyFilter.ts
-const getPartitionKeyFilter = (partitionKey) => serializeClauses([{
-	key: CompositeKeyPropertyNames.partitionKey,
-	operator: "eq",
-	value: partitionKey
-}]);
-// src/services/transformer/serializeSearchClauses.ts
-const serializeSearchClauses = (clauses) => serializeClausesCore(clauses, false);
-export { AZURE_MAX_BATCH_SIZE, AZURE_MAX_PAGE_SIZE, AZURE_MAX_QUEUE_VISIBILITY_TIMEOUT_MS, AZURE_MAX_STRING_PROPERTY_LENGTH, BinaryOperator, BinaryOperators, CLAUSE_REGEX, CompositeKey, CompositeKeyPropertyNames, DATETIME_LITERAL_PREFIX, KEYS_TO_CAPITALIZE, KEYS_TO_UNCAPITALIZE, RangeOperators, SERIALIZABLE_VALUE_MAX_LENGTH, SearchOperator, UnaryOperator, deserializeClause, deserializeKey, deserializeValue, escapeValue, getPartitionKeyFilter, getSearchNonNullClause, getSearchNullClause, getTableNullClause, serializableValueSchema, serializeClause, serializeClauses, serializeClausesCore, serializeKey, serializeSearchClauses, serializeValue };