@esposter/azure 4.2.0 → 4.3.3

package/README.md

@@ -26,6 +26,8 @@ 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.
+
 ### Clauses
 
 A `Clause<T>` is a filter condition expressed against a property of `T`, and it is what the OData string is

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+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

@@ -0,0 +1,167 @@
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esposter/azure",
-  "version": "4.2.0",
+  "version": "4.3.3",
   "description": "The Azure wire conventions Esposter's clients and its mocks both speak — OData filter clauses, entity key casing, and service limits.",
   "keywords": [
     "azure",
@@ -38,23 +38,18 @@
   },
   "scripts": {
     "build": "tsdown",
-    "format": "oxfmt",
-    "format:check": "oxfmt --check",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "test": "vitest",
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@esposter/shared": "4.2.0"
+    "@esposter/shared": "4.3.3"
   },
   "devDependencies": {
-    "@arethetypeswrong/core": "^0.18.5",
-    "@esposter/configuration": "4.2.0",
-    "publint": "^0.3.25",
+    "@esposter/configuration": "4.3.3",
     "tsdown": "^0.23.1",
-    "type-fest": "^5.10.0",
-    "vitest": "^5.0.4"
+    "type-fest": "^5.10.0"
   },
   "peerDependencies": {
     "@azure/data-tables": "^13.3.2",
@@ -63,5 +58,5 @@
   "inlinedDependencies": {
     "type-fest": "5.10.0"
   },
-  "gitHead": "fef4971cf6a621a2c1850f32fcec19ee4ec0de99"
+  "gitHead": "955bbc130ad9b28877fd4ae8efc73a045141ce01"
 }