@esposter/azure 4.3.3 → 4.5.0

package/README.md

@@ -5,35 +5,50 @@
 [![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.
+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](https://github.com/Esposter/Esposter/tree/main/openspec/specs).
 
 ## Table of Contents
 
 - 🚀 [Getting Started](#getting-started)
-- 📖 [Documentation](#documentation)
+- 🧩 [Key Exports](#key-exports)
 - ⚖️ [License](#license)
 
 ---
 
 ## <a name="getting-started">🚀 Getting Started</a>
 
+Install the package:
+
 ```bash
 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
 
-A `Clause<T>` is a filter condition expressed against a property of `T`, and it is what the OData string is
-built from rather than the string being assembled by hand. `BinaryOperator` covers the comparisons Table
-Storage understands; `SearchOperator` covers the collection predicates only Azure Search does; `UnaryOperator`
-is how clauses are combined.
+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.
 
 ```ts
 import type { Clause } from "@esposter/azure";
@@ -45,10 +60,12 @@ const clause: Clause<{ createdAt: Date }> = { key: "createdAt", operator: Binary
 
 ### Values
 
-`serializeValue` renders a `SerializableValue` the way the target service expects — Table Storage wants a
-`datetime'<iso>'` literal for a `Date`, Search wants the bare ISO string, and `isTableFilter` selects between
-them. Strings go through `escapeValue`, which doubles embedded single quotes so a value can never close its own
-literal and append filter syntax of its own.
+`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.
 
 ```ts
 import { escapeValue, serializeValue } from "@esposter/azure";
@@ -56,11 +73,14 @@ 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.
+`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.
 
 ```ts
 import { BinaryOperator, CompositeKeyPropertyNames, getTableNullClause, serializeClauses } from "@esposter/azure";
@@ -72,17 +92,16 @@ 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.
+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 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.
+`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.
 
 ```ts
 import { CompositeKey, CompositeKeyPropertyNames, serializeKey } from "@esposter/azure";
@@ -90,19 +109,7 @@ import { CompositeKey, CompositeKeyPropertyNames, serializeKey } from "@esposter
 
 ### Limits
 
-`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
-```
+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.
 
 ## <a name="license">⚖️ License</a>
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { z } from "zod";
 import { PropertyNames } from "@esposter/shared";
+import { z } from "zod";
 import { TableEntity } from "@azure/data-tables";
 export declare enum SearchOperator {
   ArrayAny = "arrayAny",
@@ -137,12 +137,16 @@ 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 MAX_BLOB_BATCH_DELETIONS = 256;
+export declare const MAX_EVENT_GRID_PUBLISH_REQUEST_BYTES: number;
+export declare const MAX_EVENT_GRID_PUBLISH_BYTES: number;
+export declare const MAX_EVENT_GRID_PUBLISH_EVENT_COUNT = 5e3;
 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 checkIsBinaryOperator: (value: string) => value is BinaryOperator;
 export declare const DATETIME_LITERAL_PREFIX = "datetime'";
 export declare const CLAUSE_REGEX: RegExp;
 export declare const deserializeClause: (serializedClause: string) => Extract<Clause<Record<string, unknown>>, {
@@ -151,6 +155,8 @@ export declare const deserializeClause: (serializedClause: string) => Extract<Cl
 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 parseIsoDate: (isoValue: string) => Date | undefined;
+export declare const RangeOperators: (BinaryOperator | SearchOperator)[];
 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;

package/dist/index.js

@@ -1,5 +1,5 @@
+import { InvalidOperationError, KIBIBYTE, NotFoundError, Operation, capitalize, getPropertyNames, getResult, normalizeString, takeOne, uncapitalize } from "@esposter/shared";
 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";
@@ -23,6 +23,10 @@ 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;
+const MAX_BLOB_BATCH_DELETIONS = 256;
+const MAX_EVENT_GRID_PUBLISH_REQUEST_BYTES = 1024 * KIBIBYTE;
+const MAX_EVENT_GRID_PUBLISH_BYTES = MAX_EVENT_GRID_PUBLISH_REQUEST_BYTES / 2;
+const MAX_EVENT_GRID_PUBLISH_EVENT_COUNT = 5e3;
 // src/models/shared/SerializableValue.ts
 const serializableValueSchema = z.union([
 	z.boolean(),
@@ -67,13 +71,8 @@ const getTableNullClause = (key) => ({
 });
 // 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/checkIsBinaryOperator.ts
+const checkIsBinaryOperator = (value) => BinaryOperators.some((binaryOperator) => binaryOperator === value);
 // src/services/transformer/constants.ts
 const DATETIME_LITERAL_PREFIX = "datetime'";
 const VALUE_REGEX = [
@@ -87,8 +86,9 @@ const VALUE_REGEX = [
 	"'(?:[^']|'')*'"
 ].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
+// src/services/transformer/parseIsoDate.ts
 const parseIsoDate = (isoValue) => getResult(() => new Date(Temporal.Instant.from(isoValue).epochMilliseconds)).unwrapOr(void 0);
+// src/services/transformer/deserializeValue.ts
 const deserializeValue = (serializedValue) => {
 	if (serializedValue === String(true)) return true;
 	else if (serializedValue === String(false)) return false;
@@ -106,15 +106,24 @@ const deserializeClause = (serializedClause) => {
 	if (!match) throw new NotFoundError(deserializeClause.name, normalizedClause);
 	const groups = match.groups;
 	if (!groups) throw new NotFoundError(deserializeClause.name, normalizedClause);
+	const operator = groups.operator.toLowerCase();
+	if (!checkIsBinaryOperator(operator)) throw new NotFoundError(deserializeClause.name, normalizedClause);
 	return {
 		key: deserializeKey(groups.key),
 		not: Boolean(groups.not),
-		operator: groups.operator.toLowerCase(),
+		operator,
 		value: deserializeValue(groups.value)
 	};
 };
 // src/services/transformer/escapeValue.ts
 const escapeValue = (value) => `'${value.replaceAll("'", "''")}'`;
+// src/services/transformer/RangeOperators.ts
+const RangeOperators = [
+	"ge",
+	"gt",
+	"le",
+	"lt"
+];
 // src/services/transformer/serializeValue.ts
 const serializeValue = (value, isTableFilter = false) => {
 	if (value instanceof Date) return isTableFilter ? `${DATETIME_LITERAL_PREFIX}${value.toISOString()}'` : value.toISOString();
@@ -164,4 +173,4 @@ const getPartitionKeyFilter = (partitionKey) => serializeClauses([{
 }]);
 // 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 };
+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, MAX_BLOB_BATCH_DELETIONS, MAX_EVENT_GRID_PUBLISH_BYTES, MAX_EVENT_GRID_PUBLISH_EVENT_COUNT, MAX_EVENT_GRID_PUBLISH_REQUEST_BYTES, RangeOperators, SERIALIZABLE_VALUE_MAX_LENGTH, SearchOperator, UnaryOperator, checkIsBinaryOperator, deserializeClause, deserializeKey, deserializeValue, escapeValue, getPartitionKeyFilter, getSearchNonNullClause, getSearchNullClause, getTableNullClause, parseIsoDate, serializableValueSchema, serializeClause, serializeClauses, serializeClausesCore, serializeKey, serializeSearchClauses, serializeValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esposter/azure",
-  "version": "4.3.3",
+  "version": "4.5.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.5.0"
   },
   "devDependencies": {
-    "@esposter/configuration": "4.3.3",
-    "tsdown": "^0.23.1",
+    "@esposter/configuration": "4.5.0",
+    "tsdown": "^0.23.5",
     "type-fest": "^5.10.0"
   },
   "peerDependencies": {
@@ -58,5 +58,5 @@
   "inlinedDependencies": {
     "type-fest": "5.10.0"
   },
-  "gitHead": "955bbc130ad9b28877fd4ae8efc73a045141ce01"
+  "gitHead": "e30c001f3b4b15693e75fb53092d62a97ade4d2b"
 }