@puzzle-ui/storage 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @puzzle-ui/storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vendor-neutral storage contracts for Puzzle.
+
+This package defines the persistence API used by Puzzle Auth and other
+packages. It does not depend on a database vendor, database SDK, framework,
+or runtime-specific implementation.
+
+## Responsibilities
+
+- Typed collection and record contracts.
+- Query AST and cursor pagination contracts.
+- CRUD, upsert and conditional write contracts.
+- Optimistic concurrency through record revisions.
+- Capability discovery.
+- Atomic batch contract.
+- Collection schemas and index definitions.
+- Migration contracts and migration status.
+- Reusable adapter conformance requirements.
+
+## Architecture
+
+Database-specific implementations belong in separate packages:
+
+- `@puzzle-ui/storage-mongodb`
+- `@puzzle-ui/storage-d1`
+
+Neither adapter may leak its database SDK or query language through this
+package.
+
+## Records
+
+Every persisted record has:
+
+- `id`
+- `createdAt`
+- `updatedAt`
+- `revision`
+
+The revision is incremented by successful updates. Adapters must use it
+for optimistic concurrency when a caller supplies `expectedRevision`.
+
+## Atomicity
+
+An adapter may advertise `atomicBatch: true` only when it guarantees
+all-or-nothing execution.
+
+If a batch fails, all changes made by that batch must be rolled back.
+Adapters without this guarantee must reject `atomicBatch` calls with
+`StorageAtomicityError`.
+
+Security-critical operations must fail closed when the required
+capability is unavailable.
+
+## Query contract
+
+Queries use a vendor-neutral AST:
+
+- `eq`, `ne`
+- `in`, `notIn`
+- `gt`, `gte`, `lt`, `lte`
+- `exists`
+- nested `and` and `or`
+- ordering
+- offset and limit
+- cursor pagination
+
+Adapters are responsible for translating this AST into their native
+query mechanism without changing its semantics.
+
+## Schemas and indexes
+
+Collection schemas validate records at the storage boundary.
+
+Indexes can declare:
+
+- Multiple indexed fields.
+- Uniqueness.
+- TTL expiration.
+
+An adapter must report unsupported index capabilities instead of
+silently ignoring requested guarantees.
+
+## Migrations
+
+Migrations are explicit and versioned. They are never run implicitly
+during ordinary reads or writes.
+
+A migration adapter must provide durable migration status and prevent
+concurrent migration runners from applying the same migration twice.
+
+## Adapter requirements
+
+Every production adapter must pass the same conformance suite.
+
+At minimum, conformance must verify:
+
+- CRUD and upsert semantics.
+- Query operator semantics.
+- Serialization of dates and null values.
+- Conditional writes and revision conflicts.
+- Unique constraint behavior.
+- Cursor pagination.
+- Atomic batch rollback.
+- Capability reporting.
+- Migration ordering and concurrency.
+
+## Build
+
+```sh
+bun run build
+bun run typecheck
+```
+
+The typecheck includes all files under `tests/conformance` and loads Bun's
+test types for their `bun:test` imports.
+
+This package contains contracts only. It does not provide a production
+database implementation or an in-memory persistence implementation.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sjoerd van Den Berg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/errors/storage.errors.cjs

@@ -0,0 +1,55 @@
+// src/errors/storage.errors.ts
+var StorageError = class extends Error {
+	code;
+	cause;
+	details;
+	constructor(code, message, options) {
+		super(message);
+		this.name = "StorageError";
+		this.code = code;
+		this.cause = options?.cause;
+		this.details = options?.details;
+	}
+};
+var StorageCapabilityError = class extends StorageError {
+	capability;
+	constructor(capability, message = `Storage adapter does not support required capability: ${capability}`) {
+		super("CAPABILITY", message, { details: { capability } });
+		this.name = "StorageCapabilityError";
+		this.capability = capability;
+	}
+};
+var StorageConflictError = class extends StorageError {
+	constructor(message = "The storage operation conflicted with the current record state.") {
+		super("CONFLICT", message);
+		this.name = "StorageConflictError";
+	}
+};
+var StorageDuplicateError = class extends StorageError {
+	constraint;
+	constructor(constraint) {
+		super("DUPLICATE", `A record violates the unique constraint "${constraint}".`, { details: { constraint } });
+		this.name = "StorageDuplicateError";
+		this.constraint = constraint;
+	}
+};
+var StorageValidationError = class extends StorageError {
+	constructor(message, details) {
+		super("VALIDATION", message, { details });
+		this.name = "StorageValidationError";
+	}
+};
+var StorageAtomicityError = class extends StorageError {
+	constructor(message = "The adapter cannot guarantee atomic execution and rollback.") {
+		super("ATOMICITY", message);
+		this.name = "StorageAtomicityError";
+	}
+};
+exports.StorageAtomicityError = StorageAtomicityError;
+exports.StorageCapabilityError = StorageCapabilityError;
+exports.StorageConflictError = StorageConflictError;
+exports.StorageDuplicateError = StorageDuplicateError;
+exports.StorageError = StorageError;
+exports.StorageValidationError = StorageValidationError;
+
+//# sourceMappingURL=storage.errors.cjs.map

package/dist/errors/storage.errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.errors.cjs","names":[],"sources":["../../src/errors/storage.errors.ts"],"sourcesContent":["export type StorageErrorCode =\n  | \"NOT_FOUND\"\n  | \"CONFLICT\"\n  | \"DUPLICATE\"\n  | \"VALIDATION\"\n  | \"CAPABILITY\"\n  | \"ATOMICITY\"\n  | \"MIGRATION\"\n  | \"QUERY\"\n  | \"UNKNOWN\";\n\nexport class StorageError extends Error {\n  readonly code: StorageErrorCode;\n  override readonly cause?: unknown;\n  readonly details?: Readonly<Record<string, unknown>>;\n\n  constructor(\n    code: StorageErrorCode,\n    message: string,\n    options?: {\n      readonly cause?: unknown;\n      readonly details?: Readonly<Record<string, unknown>>;\n    },\n  ) {\n    super(message);\n    this.name = \"StorageError\";\n    this.code = code;\n    this.cause = options?.cause;\n    this.details = options?.details;\n  }\n}\n\nexport class StorageCapabilityError extends StorageError {\n  readonly capability: string;\n\n  constructor(\n    capability: string,\n    message = `Storage adapter does not support required capability: ${capability}`,\n  ) {\n    super(\"CAPABILITY\", message, {\n      details: { capability },\n    });\n\n    this.name = \"StorageCapabilityError\";\n    this.capability = capability;\n  }\n}\n\nexport class StorageConflictError extends StorageError {\n  constructor(\n    message = \"The storage operation conflicted with the current record state.\",\n  ) {\n    super(\"CONFLICT\", message);\n    this.name = \"StorageConflictError\";\n  }\n}\n\nexport class StorageDuplicateError extends StorageError {\n  readonly constraint: string;\n\n  constructor(constraint: string) {\n    super(\n      \"DUPLICATE\",\n      `A record violates the unique constraint \"${constraint}\".`,\n      {\n        details: { constraint },\n      },\n    );\n\n    this.name = \"StorageDuplicateError\";\n    this.constraint = constraint;\n  }\n}\n\nexport class StorageValidationError extends StorageError {\n  constructor(message: string, details?: Readonly<Record<string, unknown>>) {\n    super(\"VALIDATION\", message, { details });\n    this.name = \"StorageValidationError\";\n  }\n}\n\nexport class StorageAtomicityError extends StorageError {\n  constructor(\n    message = \"The adapter cannot guarantee atomic execution and rollback.\",\n  ) {\n    super(\"ATOMICITY\", message);\n    this.name = \"StorageAtomicityError\";\n  }\n}\n"],"mappings":";AAWA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CACA;CAEA,YACE,MACA,SACA,SAIA;EACA,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,QAAQ,SAAS;EACtB,KAAK,UAAU,SAAS;CAC1B;AACF;AAEA,IAAa,yBAAb,cAA4C,aAAa;CACvD;CAEA,YACE,YACA,UAAU,yDAAyD,cACnE;EACA,MAAM,cAAc,SAAS,EAC3B,SAAS,EAAE,WAAW,EACxB,CAAC;EAED,KAAK,OAAO;EACZ,KAAK,aAAa;CACpB;AACF;AAEA,IAAa,uBAAb,cAA0C,aAAa;CACrD,YACE,UAAU,mEACV;EACA,MAAM,YAAY,OAAO;EACzB,KAAK,OAAO;CACd;AACF;AAEA,IAAa,wBAAb,cAA2C,aAAa;CACtD;CAEA,YAAY,YAAoB;EAC9B,MACE,aACA,4CAA4C,WAAW,KACvD,EACE,SAAS,EAAE,WAAW,EACxB,CACF;EAEA,KAAK,OAAO;EACZ,KAAK,aAAa;CACpB;AACF;AAEA,IAAa,yBAAb,cAA4C,aAAa;CACvD,YAAY,SAAiB,SAA6C;EACxE,MAAM,cAAc,SAAS,EAAE,QAAQ,CAAC;EACxC,KAAK,OAAO;CACd;AACF;AAEA,IAAa,wBAAb,cAA2C,aAAa;CACtD,YACE,UAAU,+DACV;EACA,MAAM,aAAa,OAAO;EAC1B,KAAK,OAAO;CACd;AACF"}

package/dist/errors/storage.errors.d.cts

@@ -0,0 +1,27 @@
+export type StorageErrorCode = "NOT_FOUND" | "CONFLICT" | "DUPLICATE" | "VALIDATION" | "CAPABILITY" | "ATOMICITY" | "MIGRATION" | "QUERY" | "UNKNOWN";
+export declare class StorageError extends Error {
+  readonly code: StorageErrorCode;
+  readonly cause?: unknown;
+  readonly details?: Readonly<Record<string, unknown>>;
+  constructor(code: StorageErrorCode, message: string, options?: {
+    readonly cause?: unknown;
+    readonly details?: Readonly<Record<string, unknown>>;
+  });
+}
+export declare class StorageCapabilityError extends StorageError {
+  readonly capability: string;
+  constructor(capability: string, message?: string);
+}
+export declare class StorageConflictError extends StorageError {
+  constructor(message?: string);
+}
+export declare class StorageDuplicateError extends StorageError {
+  readonly constraint: string;
+  constructor(constraint: string);
+}
+export declare class StorageValidationError extends StorageError {
+  constructor(message: string, details?: Readonly<Record<string, unknown>>);
+}
+export declare class StorageAtomicityError extends StorageError {
+  constructor(message?: string);
+}

package/dist/errors/storage.errors.d.ts

@@ -0,0 +1,27 @@
+export type StorageErrorCode = "NOT_FOUND" | "CONFLICT" | "DUPLICATE" | "VALIDATION" | "CAPABILITY" | "ATOMICITY" | "MIGRATION" | "QUERY" | "UNKNOWN";
+export declare class StorageError extends Error {
+  readonly code: StorageErrorCode;
+  readonly cause?: unknown;
+  readonly details?: Readonly<Record<string, unknown>>;
+  constructor(code: StorageErrorCode, message: string, options?: {
+    readonly cause?: unknown;
+    readonly details?: Readonly<Record<string, unknown>>;
+  });
+}
+export declare class StorageCapabilityError extends StorageError {
+  readonly capability: string;
+  constructor(capability: string, message?: string);
+}
+export declare class StorageConflictError extends StorageError {
+  constructor(message?: string);
+}
+export declare class StorageDuplicateError extends StorageError {
+  readonly constraint: string;
+  constructor(constraint: string);
+}
+export declare class StorageValidationError extends StorageError {
+  constructor(message: string, details?: Readonly<Record<string, unknown>>);
+}
+export declare class StorageAtomicityError extends StorageError {
+  constructor(message?: string);
+}

package/dist/errors/storage.errors.js

@@ -0,0 +1,50 @@
+// src/errors/storage.errors.ts
+var StorageError = class extends Error {
+	code;
+	cause;
+	details;
+	constructor(code, message, options) {
+		super(message);
+		this.name = "StorageError";
+		this.code = code;
+		this.cause = options?.cause;
+		this.details = options?.details;
+	}
+};
+var StorageCapabilityError = class extends StorageError {
+	capability;
+	constructor(capability, message = `Storage adapter does not support required capability: ${capability}`) {
+		super("CAPABILITY", message, { details: { capability } });
+		this.name = "StorageCapabilityError";
+		this.capability = capability;
+	}
+};
+var StorageConflictError = class extends StorageError {
+	constructor(message = "The storage operation conflicted with the current record state.") {
+		super("CONFLICT", message);
+		this.name = "StorageConflictError";
+	}
+};
+var StorageDuplicateError = class extends StorageError {
+	constraint;
+	constructor(constraint) {
+		super("DUPLICATE", `A record violates the unique constraint "${constraint}".`, { details: { constraint } });
+		this.name = "StorageDuplicateError";
+		this.constraint = constraint;
+	}
+};
+var StorageValidationError = class extends StorageError {
+	constructor(message, details) {
+		super("VALIDATION", message, { details });
+		this.name = "StorageValidationError";
+	}
+};
+var StorageAtomicityError = class extends StorageError {
+	constructor(message = "The adapter cannot guarantee atomic execution and rollback.") {
+		super("ATOMICITY", message);
+		this.name = "StorageAtomicityError";
+	}
+};
+export { StorageAtomicityError, StorageCapabilityError, StorageConflictError, StorageDuplicateError, StorageError, StorageValidationError };
+
+//# sourceMappingURL=storage.errors.js.map

package/dist/errors/storage.errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.errors.js","names":[],"sources":["../../src/errors/storage.errors.ts"],"sourcesContent":["export type StorageErrorCode =\n  | \"NOT_FOUND\"\n  | \"CONFLICT\"\n  | \"DUPLICATE\"\n  | \"VALIDATION\"\n  | \"CAPABILITY\"\n  | \"ATOMICITY\"\n  | \"MIGRATION\"\n  | \"QUERY\"\n  | \"UNKNOWN\";\n\nexport class StorageError extends Error {\n  readonly code: StorageErrorCode;\n  override readonly cause?: unknown;\n  readonly details?: Readonly<Record<string, unknown>>;\n\n  constructor(\n    code: StorageErrorCode,\n    message: string,\n    options?: {\n      readonly cause?: unknown;\n      readonly details?: Readonly<Record<string, unknown>>;\n    },\n  ) {\n    super(message);\n    this.name = \"StorageError\";\n    this.code = code;\n    this.cause = options?.cause;\n    this.details = options?.details;\n  }\n}\n\nexport class StorageCapabilityError extends StorageError {\n  readonly capability: string;\n\n  constructor(\n    capability: string,\n    message = `Storage adapter does not support required capability: ${capability}`,\n  ) {\n    super(\"CAPABILITY\", message, {\n      details: { capability },\n    });\n\n    this.name = \"StorageCapabilityError\";\n    this.capability = capability;\n  }\n}\n\nexport class StorageConflictError extends StorageError {\n  constructor(\n    message = \"The storage operation conflicted with the current record state.\",\n  ) {\n    super(\"CONFLICT\", message);\n    this.name = \"StorageConflictError\";\n  }\n}\n\nexport class StorageDuplicateError extends StorageError {\n  readonly constraint: string;\n\n  constructor(constraint: string) {\n    super(\n      \"DUPLICATE\",\n      `A record violates the unique constraint \"${constraint}\".`,\n      {\n        details: { constraint },\n      },\n    );\n\n    this.name = \"StorageDuplicateError\";\n    this.constraint = constraint;\n  }\n}\n\nexport class StorageValidationError extends StorageError {\n  constructor(message: string, details?: Readonly<Record<string, unknown>>) {\n    super(\"VALIDATION\", message, { details });\n    this.name = \"StorageValidationError\";\n  }\n}\n\nexport class StorageAtomicityError extends StorageError {\n  constructor(\n    message = \"The adapter cannot guarantee atomic execution and rollback.\",\n  ) {\n    super(\"ATOMICITY\", message);\n    this.name = \"StorageAtomicityError\";\n  }\n}\n"],"mappings":";AAWA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CACA;CAEA,YACE,MACA,SACA,SAIA;EACA,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,QAAQ,SAAS;EACtB,KAAK,UAAU,SAAS;CAC1B;AACF;AAEA,IAAa,yBAAb,cAA4C,aAAa;CACvD;CAEA,YACE,YACA,UAAU,yDAAyD,cACnE;EACA,MAAM,cAAc,SAAS,EAC3B,SAAS,EAAE,WAAW,EACxB,CAAC;EAED,KAAK,OAAO;EACZ,KAAK,aAAa;CACpB;AACF;AAEA,IAAa,uBAAb,cAA0C,aAAa;CACrD,YACE,UAAU,mEACV;EACA,MAAM,YAAY,OAAO;EACzB,KAAK,OAAO;CACd;AACF;AAEA,IAAa,wBAAb,cAA2C,aAAa;CACtD;CAEA,YAAY,YAAoB;EAC9B,MACE,aACA,4CAA4C,WAAW,KACvD,EACE,SAAS,EAAE,WAAW,EACxB,CACF;EAEA,KAAK,OAAO;EACZ,KAAK,aAAa;CACpB;AACF;AAEA,IAAa,yBAAb,cAA4C,aAAa;CACvD,YAAY,SAAiB,SAA6C;EACxE,MAAM,cAAc,SAAS,EAAE,QAAQ,CAAC;EACxC,KAAK,OAAO;CACd;AACF;AAEA,IAAa,wBAAb,cAA2C,aAAa;CACtD,YACE,UAAU,+DACV;EACA,MAAM,aAAa,OAAO;EAC1B,KAAK,OAAO;CACd;AACF"}

package/dist/index.cjs

@@ -0,0 +1,13 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_capabilities_types = require("./types/capabilities.types.cjs");
+const require_storage_errors = require("./errors/storage.errors.cjs");
+const require_query_utils = require("./utils/query.utils.cjs");
+exports.DEFAULT_STORAGE_CAPABILITIES = require_capabilities_types.DEFAULT_STORAGE_CAPABILITIES;
+exports.StorageAtomicityError = require_storage_errors.StorageAtomicityError;
+exports.StorageCapabilityError = require_storage_errors.StorageCapabilityError;
+exports.StorageConflictError = require_storage_errors.StorageConflictError;
+exports.StorageDuplicateError = require_storage_errors.StorageDuplicateError;
+exports.StorageError = require_storage_errors.StorageError;
+exports.StorageValidationError = require_storage_errors.StorageValidationError;
+exports.validateQuery = require_query_utils.validateQuery;
+exports.validateWhere = require_query_utils.validateWhere;

package/dist/index.d.cts

@@ -0,0 +1,9 @@
+import { StorageCollection, StorageCollectionName, StorageCollectionOptions, StorageField, StorageIndex, StorageRecord, StorageScalar, StorageSchema } from "./types/collection.types.cjs";
+import { StorageComparison, StorageCursor, StorageCursorQuery, StorageOrder, StoragePage, StorageQuery, StorageWhere } from "./types/query.types.cjs";
+import { DEFAULT_STORAGE_CAPABILITIES, StorageCapabilities, StorageCapability, StorageCapabilityReport } from "./types/capabilities.types.cjs";
+import { StorageAdapter, StorageAdapterOptions, StorageBatchOperation, StorageBatchResult, StorageCondition, StorageInsert, StorageUpdate } from "./types/adapter.types.cjs";
+import { StorageMigration, StorageMigrationAdapter, StorageMigrationContext, StorageMigrationOperation, StorageMigrationOptions, StorageMigrationRecord, StorageMigrationResult, StorageMigrationStatus } from "./types/migration.types.cjs";
+import { StorageIndexDefinition, StorageSchemaAdapter, StorageSchemaRegistry } from "./types/schema.types.cjs";
+import { StorageAtomicityError, StorageCapabilityError, StorageConflictError, StorageDuplicateError, StorageError, StorageValidationError } from "./errors/storage.errors.cjs";
+import { validateQuery, validateWhere } from "./utils/query.utils.cjs";
+export { DEFAULT_STORAGE_CAPABILITIES, type StorageAdapter, type StorageAdapterOptions, StorageAtomicityError, type StorageBatchOperation, type StorageBatchResult, type StorageCapabilities, type StorageCapability, StorageCapabilityError, type StorageCapabilityReport, type StorageCollection, type StorageCollectionName, type StorageCollectionOptions, type StorageComparison, type StorageCondition, StorageConflictError, type StorageCursor, type StorageCursorQuery, StorageDuplicateError, StorageError, type StorageField, type StorageIndex, type StorageIndexDefinition, type StorageInsert, type StorageMigration, type StorageMigrationAdapter, type StorageMigrationContext, type StorageMigrationOperation, type StorageMigrationOptions, type StorageMigrationRecord, type StorageMigrationResult, type StorageMigrationStatus, type StorageOrder, type StoragePage, type StorageQuery, type StorageRecord, type StorageScalar, type StorageSchema, type StorageSchemaAdapter, type StorageSchemaRegistry, type StorageUpdate, StorageValidationError, type StorageWhere, validateQuery, validateWhere };

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { StorageCollection, StorageCollectionName, StorageCollectionOptions, StorageField, StorageIndex, StorageRecord, StorageScalar, StorageSchema } from "./types/collection.types.js";
+import { StorageComparison, StorageCursor, StorageCursorQuery, StorageOrder, StoragePage, StorageQuery, StorageWhere } from "./types/query.types.js";
+import { DEFAULT_STORAGE_CAPABILITIES, StorageCapabilities, StorageCapability, StorageCapabilityReport } from "./types/capabilities.types.js";
+import { StorageAdapter, StorageAdapterOptions, StorageBatchOperation, StorageBatchResult, StorageCondition, StorageInsert, StorageUpdate } from "./types/adapter.types.js";
+import { StorageMigration, StorageMigrationAdapter, StorageMigrationContext, StorageMigrationOperation, StorageMigrationOptions, StorageMigrationRecord, StorageMigrationResult, StorageMigrationStatus } from "./types/migration.types.js";
+import { StorageIndexDefinition, StorageSchemaAdapter, StorageSchemaRegistry } from "./types/schema.types.js";
+import { StorageAtomicityError, StorageCapabilityError, StorageConflictError, StorageDuplicateError, StorageError, StorageValidationError } from "./errors/storage.errors.js";
+import { validateQuery, validateWhere } from "./utils/query.utils.js";
+export { DEFAULT_STORAGE_CAPABILITIES, type StorageAdapter, type StorageAdapterOptions, StorageAtomicityError, type StorageBatchOperation, type StorageBatchResult, type StorageCapabilities, type StorageCapability, StorageCapabilityError, type StorageCapabilityReport, type StorageCollection, type StorageCollectionName, type StorageCollectionOptions, type StorageComparison, type StorageCondition, StorageConflictError, type StorageCursor, type StorageCursorQuery, StorageDuplicateError, StorageError, type StorageField, type StorageIndex, type StorageIndexDefinition, type StorageInsert, type StorageMigration, type StorageMigrationAdapter, type StorageMigrationContext, type StorageMigrationOperation, type StorageMigrationOptions, type StorageMigrationRecord, type StorageMigrationResult, type StorageMigrationStatus, type StorageOrder, type StoragePage, type StorageQuery, type StorageRecord, type StorageScalar, type StorageSchema, type StorageSchemaAdapter, type StorageSchemaRegistry, type StorageUpdate, StorageValidationError, type StorageWhere, validateQuery, validateWhere };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { DEFAULT_STORAGE_CAPABILITIES } from "./types/capabilities.types.js";
+import { StorageAtomicityError, StorageCapabilityError, StorageConflictError, StorageDuplicateError, StorageError, StorageValidationError } from "./errors/storage.errors.js";
+import { validateQuery, validateWhere } from "./utils/query.utils.js";
+export { DEFAULT_STORAGE_CAPABILITIES, StorageAtomicityError, StorageCapabilityError, StorageConflictError, StorageDuplicateError, StorageError, StorageValidationError, validateQuery, validateWhere };

package/dist/types/adapter.types.d.cts

@@ -0,0 +1,68 @@
+import { StorageCollection, StorageCollectionName, StorageRecord } from "./collection.types.cjs";
+import { StorageCapabilities, StorageCapabilityReport } from "./capabilities.types.cjs";
+import { StorageCursorQuery, StoragePage, StorageQuery } from "./query.types.cjs";
+export type StorageInsert<T extends StorageRecord> = Omit<T, "createdAt" | "updatedAt" | "revision"> & {
+  readonly createdAt?: Date;
+  readonly updatedAt?: Date;
+  readonly revision?: number;
+};
+export type StorageUpdate<T extends StorageRecord> = Partial<Omit<T, "id" | "createdAt" | "revision">>;
+export type StorageCondition = {
+  readonly expectedRevision?: number;
+  readonly expectedUpdatedAt?: Date;
+};
+type StorageBatchOperationItem<T extends StorageRecord> = {
+  readonly type: "insert";
+  readonly collection: StorageCollectionName;
+  readonly record: StorageInsert<T>;
+} | {
+  readonly type: "update";
+  readonly collection: StorageCollectionName;
+  readonly id: string;
+  readonly condition?: StorageCondition;
+  readonly changes: StorageUpdate<T>;
+} | {
+  readonly type: "delete";
+  readonly collection: StorageCollectionName;
+  readonly id: string;
+  readonly condition?: StorageCondition;
+};
+/**
+ * Distributes over unions so an atomic batch can contain records
+ * from different collections with different record types.
+ */
+export type StorageBatchOperation<T extends StorageRecord> = T extends StorageRecord ? StorageBatchOperationItem<T> : never;
+export type StorageBatchResult<T extends StorageRecord> = {
+  readonly results: readonly ({
+    readonly type: "insert";
+    readonly record: T;
+  } | {
+    readonly type: "update";
+    readonly record: T | null;
+  } | {
+    readonly type: "delete";
+    readonly deleted: boolean;
+  })[];
+};
+export type StorageAdapterOptions = {
+  readonly requireAtomicBatch?: boolean;
+};
+export interface StorageAdapter {
+  readonly capabilities: StorageCapabilities;
+  getCapabilities(): StorageCapabilityReport;
+  registerCollection<T extends StorageRecord>(collection: StorageCollection<T>): Promise<void>;
+  findById<T extends StorageRecord>(collection: StorageCollectionName, id: string): Promise<T | null>;
+  findOne<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>): Promise<T | null>;
+  findMany<T extends StorageRecord>(collection: StorageCollectionName, query?: StorageQuery<T>): Promise<readonly T[]>;
+  findPage<T extends StorageRecord>(collection: StorageCollectionName, query: StorageCursorQuery<T>): Promise<StoragePage<T>>;
+  insert<T extends StorageRecord>(collection: StorageCollectionName, record: StorageInsert<T>): Promise<T>;
+  upsert<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>, record: StorageInsert<T>): Promise<T>;
+  update<T extends StorageRecord>(collection: StorageCollectionName, id: string, changes: StorageUpdate<T>, condition?: StorageCondition): Promise<T | null>;
+  updateMany<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>, changes: StorageUpdate<T>): Promise<number>;
+  delete<T extends StorageRecord>(collection: StorageCollectionName, id: string, condition?: StorageCondition): Promise<boolean>;
+  deleteMany<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>): Promise<number>;
+  exists<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>): Promise<boolean>;
+  count<T extends StorageRecord>(collection: StorageCollectionName, query?: StorageQuery<T>): Promise<number>;
+  atomicBatch<T extends StorageRecord>(operations: readonly StorageBatchOperation<T>[]): Promise<StorageBatchResult<T>>;
+}
+export {};

package/dist/types/adapter.types.d.ts

@@ -0,0 +1,68 @@
+import { StorageCollection, StorageCollectionName, StorageRecord } from "./collection.types.js";
+import { StorageCapabilities, StorageCapabilityReport } from "./capabilities.types.js";
+import { StorageCursorQuery, StoragePage, StorageQuery } from "./query.types.js";
+export type StorageInsert<T extends StorageRecord> = Omit<T, "createdAt" | "updatedAt" | "revision"> & {
+  readonly createdAt?: Date;
+  readonly updatedAt?: Date;
+  readonly revision?: number;
+};
+export type StorageUpdate<T extends StorageRecord> = Partial<Omit<T, "id" | "createdAt" | "revision">>;
+export type StorageCondition = {
+  readonly expectedRevision?: number;
+  readonly expectedUpdatedAt?: Date;
+};
+type StorageBatchOperationItem<T extends StorageRecord> = {
+  readonly type: "insert";
+  readonly collection: StorageCollectionName;
+  readonly record: StorageInsert<T>;
+} | {
+  readonly type: "update";
+  readonly collection: StorageCollectionName;
+  readonly id: string;
+  readonly condition?: StorageCondition;
+  readonly changes: StorageUpdate<T>;
+} | {
+  readonly type: "delete";
+  readonly collection: StorageCollectionName;
+  readonly id: string;
+  readonly condition?: StorageCondition;
+};
+/**
+ * Distributes over unions so an atomic batch can contain records
+ * from different collections with different record types.
+ */
+export type StorageBatchOperation<T extends StorageRecord> = T extends StorageRecord ? StorageBatchOperationItem<T> : never;
+export type StorageBatchResult<T extends StorageRecord> = {
+  readonly results: readonly ({
+    readonly type: "insert";
+    readonly record: T;
+  } | {
+    readonly type: "update";
+    readonly record: T | null;
+  } | {
+    readonly type: "delete";
+    readonly deleted: boolean;
+  })[];
+};
+export type StorageAdapterOptions = {
+  readonly requireAtomicBatch?: boolean;
+};
+export interface StorageAdapter {
+  readonly capabilities: StorageCapabilities;
+  getCapabilities(): StorageCapabilityReport;
+  registerCollection<T extends StorageRecord>(collection: StorageCollection<T>): Promise<void>;
+  findById<T extends StorageRecord>(collection: StorageCollectionName, id: string): Promise<T | null>;
+  findOne<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>): Promise<T | null>;
+  findMany<T extends StorageRecord>(collection: StorageCollectionName, query?: StorageQuery<T>): Promise<readonly T[]>;
+  findPage<T extends StorageRecord>(collection: StorageCollectionName, query: StorageCursorQuery<T>): Promise<StoragePage<T>>;
+  insert<T extends StorageRecord>(collection: StorageCollectionName, record: StorageInsert<T>): Promise<T>;
+  upsert<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>, record: StorageInsert<T>): Promise<T>;
+  update<T extends StorageRecord>(collection: StorageCollectionName, id: string, changes: StorageUpdate<T>, condition?: StorageCondition): Promise<T | null>;
+  updateMany<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>, changes: StorageUpdate<T>): Promise<number>;
+  delete<T extends StorageRecord>(collection: StorageCollectionName, id: string, condition?: StorageCondition): Promise<boolean>;
+  deleteMany<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>): Promise<number>;
+  exists<T extends StorageRecord>(collection: StorageCollectionName, query: StorageQuery<T>): Promise<boolean>;
+  count<T extends StorageRecord>(collection: StorageCollectionName, query?: StorageQuery<T>): Promise<number>;
+  atomicBatch<T extends StorageRecord>(operations: readonly StorageBatchOperation<T>[]): Promise<StorageBatchResult<T>>;
+}
+export {};

package/dist/types/capabilities.types.cjs

@@ -0,0 +1,14 @@
+// src/types/capabilities.types.ts
+const DEFAULT_STORAGE_CAPABILITIES = {
+	transactions: false,
+	atomicBatch: false,
+	conditionalWrites: false,
+	uniqueConstraints: false,
+	upsert: false,
+	cursorPagination: false,
+	migrations: false,
+	ttlIndexes: false
+};
+exports.DEFAULT_STORAGE_CAPABILITIES = DEFAULT_STORAGE_CAPABILITIES;
+
+//# sourceMappingURL=capabilities.types.cjs.map

package/dist/types/capabilities.types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.types.cjs","names":[],"sources":["../../src/types/capabilities.types.ts"],"sourcesContent":["export type StorageCapabilities = {\n  readonly transactions: boolean;\n  readonly atomicBatch: boolean;\n  readonly conditionalWrites: boolean;\n  readonly uniqueConstraints: boolean;\n  readonly upsert: boolean;\n  readonly cursorPagination: boolean;\n  readonly migrations: boolean;\n  readonly ttlIndexes: boolean;\n};\n\nexport type StorageCapability = keyof StorageCapabilities;\n\nexport type StorageCapabilityReport = {\n  readonly capabilities: StorageCapabilities;\n  readonly limitations?: readonly string[];\n};\n\nexport const DEFAULT_STORAGE_CAPABILITIES: StorageCapabilities = {\n  transactions: false,\n  atomicBatch: false,\n  conditionalWrites: false,\n  uniqueConstraints: false,\n  upsert: false,\n  cursorPagination: false,\n  migrations: false,\n  ttlIndexes: false,\n};\n"],"mappings":";AAkBA,MAAa,+BAAoD;CAC/D,cAAc;CACd,aAAa;CACb,mBAAmB;CACnB,mBAAmB;CACnB,QAAQ;CACR,kBAAkB;CAClB,YAAY;CACZ,YAAY;AACd"}

package/dist/types/capabilities.types.d.cts

@@ -0,0 +1,16 @@
+export type StorageCapabilities = {
+  readonly transactions: boolean;
+  readonly atomicBatch: boolean;
+  readonly conditionalWrites: boolean;
+  readonly uniqueConstraints: boolean;
+  readonly upsert: boolean;
+  readonly cursorPagination: boolean;
+  readonly migrations: boolean;
+  readonly ttlIndexes: boolean;
+};
+export type StorageCapability = keyof StorageCapabilities;
+export type StorageCapabilityReport = {
+  readonly capabilities: StorageCapabilities;
+  readonly limitations?: readonly string[];
+};
+export declare const DEFAULT_STORAGE_CAPABILITIES: StorageCapabilities;

package/dist/types/capabilities.types.d.ts

@@ -0,0 +1,16 @@
+export type StorageCapabilities = {
+  readonly transactions: boolean;
+  readonly atomicBatch: boolean;
+  readonly conditionalWrites: boolean;
+  readonly uniqueConstraints: boolean;
+  readonly upsert: boolean;
+  readonly cursorPagination: boolean;
+  readonly migrations: boolean;
+  readonly ttlIndexes: boolean;
+};
+export type StorageCapability = keyof StorageCapabilities;
+export type StorageCapabilityReport = {
+  readonly capabilities: StorageCapabilities;
+  readonly limitations?: readonly string[];
+};
+export declare const DEFAULT_STORAGE_CAPABILITIES: StorageCapabilities;

package/dist/types/capabilities.types.js

@@ -0,0 +1,14 @@
+// src/types/capabilities.types.ts
+const DEFAULT_STORAGE_CAPABILITIES = {
+	transactions: false,
+	atomicBatch: false,
+	conditionalWrites: false,
+	uniqueConstraints: false,
+	upsert: false,
+	cursorPagination: false,
+	migrations: false,
+	ttlIndexes: false
+};
+export { DEFAULT_STORAGE_CAPABILITIES };
+
+//# sourceMappingURL=capabilities.types.js.map

package/dist/types/capabilities.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.types.js","names":[],"sources":["../../src/types/capabilities.types.ts"],"sourcesContent":["export type StorageCapabilities = {\n  readonly transactions: boolean;\n  readonly atomicBatch: boolean;\n  readonly conditionalWrites: boolean;\n  readonly uniqueConstraints: boolean;\n  readonly upsert: boolean;\n  readonly cursorPagination: boolean;\n  readonly migrations: boolean;\n  readonly ttlIndexes: boolean;\n};\n\nexport type StorageCapability = keyof StorageCapabilities;\n\nexport type StorageCapabilityReport = {\n  readonly capabilities: StorageCapabilities;\n  readonly limitations?: readonly string[];\n};\n\nexport const DEFAULT_STORAGE_CAPABILITIES: StorageCapabilities = {\n  transactions: false,\n  atomicBatch: false,\n  conditionalWrites: false,\n  uniqueConstraints: false,\n  upsert: false,\n  cursorPagination: false,\n  migrations: false,\n  ttlIndexes: false,\n};\n"],"mappings":";AAkBA,MAAa,+BAAoD;CAC/D,cAAc;CACd,aAAa;CACb,mBAAmB;CACnB,mBAAmB;CACnB,QAAQ;CACR,kBAAkB;CAClB,YAAY;CACZ,YAAY;AACd"}

package/dist/types/collection.types.d.cts

@@ -0,0 +1,25 @@
+export type StorageScalar = string | number | boolean | Date | null;
+export type StorageRecord = {
+  readonly id: string;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly revokedAt?: Date | null;
+  readonly revision: number;
+};
+export type StorageCollectionName = string;
+export type StorageField<T> = { [K in keyof T]-?: T[K] extends StorageScalar ? K : never; }[keyof T] & string;
+export type StorageCollectionOptions<T extends StorageRecord> = {
+  readonly name: StorageCollectionName;
+  readonly schema?: StorageSchema<T>;
+  readonly indexes?: readonly StorageIndex<T>[];
+};
+export type StorageCollection<T extends StorageRecord> = StorageCollectionOptions<T>;
+export type StorageSchema<T extends StorageRecord> = {
+  readonly validate: (record: unknown) => record is T;
+};
+export type StorageIndex<T extends StorageRecord> = {
+  readonly name: string;
+  readonly fields: readonly StorageField<T>[];
+  readonly unique?: boolean;
+  readonly expireAfterSeconds?: number;
+};

package/dist/types/collection.types.d.ts

@@ -0,0 +1,25 @@
+export type StorageScalar = string | number | boolean | Date | null;
+export type StorageRecord = {
+  readonly id: string;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly revokedAt?: Date | null;
+  readonly revision: number;
+};
+export type StorageCollectionName = string;
+export type StorageField<T> = { [K in keyof T]-?: T[K] extends StorageScalar ? K : never; }[keyof T] & string;
+export type StorageCollectionOptions<T extends StorageRecord> = {
+  readonly name: StorageCollectionName;
+  readonly schema?: StorageSchema<T>;
+  readonly indexes?: readonly StorageIndex<T>[];
+};
+export type StorageCollection<T extends StorageRecord> = StorageCollectionOptions<T>;
+export type StorageSchema<T extends StorageRecord> = {
+  readonly validate: (record: unknown) => record is T;
+};
+export type StorageIndex<T extends StorageRecord> = {
+  readonly name: string;
+  readonly fields: readonly StorageField<T>[];
+  readonly unique?: boolean;
+  readonly expireAfterSeconds?: number;
+};

package/dist/types/migration.types.d.cts

@@ -0,0 +1,53 @@
+export type StorageMigrationContext = {
+  readonly execute: (operation: StorageMigrationOperation) => Promise<void>;
+};
+export type StorageMigrationOperation = {
+  readonly type: "createCollection";
+  readonly collection: string;
+} | {
+  readonly type: "dropCollection";
+  readonly collection: string;
+} | {
+  readonly type: "createIndex";
+  readonly collection: string;
+  readonly name: string;
+  readonly fields: readonly string[];
+  readonly unique?: boolean;
+  readonly expireAfterSeconds?: number;
+} | {
+  readonly type: "dropIndex";
+  readonly collection: string;
+  readonly name: string;
+};
+export type StorageMigration = {
+  readonly id: string;
+  readonly version: number;
+  readonly description: string;
+  readonly up: (context: StorageMigrationContext) => Promise<void>;
+};
+export type StorageMigrationStatus = "pending" | "running" | "completed" | "failed";
+export type StorageMigrationRecord = {
+  readonly id: string;
+  readonly version: number;
+  readonly description: string;
+  readonly status: StorageMigrationStatus;
+  readonly startedAt?: Date;
+  readonly completedAt?: Date;
+  readonly error?: string;
+};
+export type StorageMigrationResult = {
+  readonly applied: readonly number[];
+  readonly skipped: readonly number[];
+  readonly currentVersion: number;
+};
+export type StorageMigrationOptions = {
+  readonly targetVersion?: number;
+  readonly dryRun?: boolean;
+};
+export interface StorageMigrationAdapter {
+  getMigrationStatus(): Promise<{
+    readonly currentVersion: number;
+    readonly migrations: readonly StorageMigrationRecord[];
+  }>;
+  runMigrations(migrations: readonly StorageMigration[], options?: StorageMigrationOptions): Promise<StorageMigrationResult>;
+}

package/dist/types/migration.types.d.ts

@@ -0,0 +1,53 @@
+export type StorageMigrationContext = {
+  readonly execute: (operation: StorageMigrationOperation) => Promise<void>;
+};
+export type StorageMigrationOperation = {
+  readonly type: "createCollection";
+  readonly collection: string;
+} | {
+  readonly type: "dropCollection";
+  readonly collection: string;
+} | {
+  readonly type: "createIndex";
+  readonly collection: string;
+  readonly name: string;
+  readonly fields: readonly string[];
+  readonly unique?: boolean;
+  readonly expireAfterSeconds?: number;
+} | {
+  readonly type: "dropIndex";
+  readonly collection: string;
+  readonly name: string;
+};
+export type StorageMigration = {
+  readonly id: string;
+  readonly version: number;
+  readonly description: string;
+  readonly up: (context: StorageMigrationContext) => Promise<void>;
+};
+export type StorageMigrationStatus = "pending" | "running" | "completed" | "failed";
+export type StorageMigrationRecord = {
+  readonly id: string;
+  readonly version: number;
+  readonly description: string;
+  readonly status: StorageMigrationStatus;
+  readonly startedAt?: Date;
+  readonly completedAt?: Date;
+  readonly error?: string;
+};
+export type StorageMigrationResult = {
+  readonly applied: readonly number[];
+  readonly skipped: readonly number[];
+  readonly currentVersion: number;
+};
+export type StorageMigrationOptions = {
+  readonly targetVersion?: number;
+  readonly dryRun?: boolean;
+};
+export interface StorageMigrationAdapter {
+  getMigrationStatus(): Promise<{
+    readonly currentVersion: number;
+    readonly migrations: readonly StorageMigrationRecord[];
+  }>;
+  runMigrations(migrations: readonly StorageMigration[], options?: StorageMigrationOptions): Promise<StorageMigrationResult>;
+}

package/dist/types/query.types.d.cts

@@ -0,0 +1,55 @@
+import { StorageRecord, StorageScalar } from "./collection.types.cjs";
+export type StorageComparison<T = StorageScalar> = {
+  readonly operator: "eq";
+  readonly value: T;
+} | {
+  readonly operator: "ne";
+  readonly value: T;
+} | {
+  readonly operator: "in";
+  readonly value: readonly T[];
+} | {
+  readonly operator: "notIn";
+  readonly value: readonly T[];
+} | {
+  readonly operator: "gt";
+  readonly value: T;
+} | {
+  readonly operator: "gte";
+  readonly value: T;
+} | {
+  readonly operator: "lt";
+  readonly value: T;
+} | {
+  readonly operator: "lte";
+  readonly value: T;
+} | {
+  readonly operator: "exists";
+  readonly value: boolean;
+};
+export type StorageWhere<T extends object> = { readonly [K in keyof T]?: T[K] extends StorageScalar ? StorageComparison<T[K]> : StorageComparison<StorageScalar>; } & {
+  readonly and?: readonly StorageWhere<T>[];
+  readonly or?: readonly StorageWhere<T>[];
+};
+export type StorageOrder<T extends object> = {
+  readonly field: keyof T & string;
+  readonly direction: "asc" | "desc";
+};
+export type StorageQuery<T extends StorageRecord> = {
+  readonly where?: StorageWhere<T>;
+  readonly orderBy?: readonly StorageOrder<T>[];
+  readonly limit?: number;
+  readonly offset?: number;
+};
+export type StorageCursor = {
+  readonly value: string;
+};
+export type StorageCursorQuery<T extends StorageRecord> = Omit<StorageQuery<T>, "offset"> & {
+  readonly first: number;
+  readonly after?: StorageCursor;
+};
+export type StoragePage<T extends StorageRecord> = {
+  readonly items: readonly T[];
+  readonly nextCursor: StorageCursor | null;
+  readonly hasNextPage: boolean;
+};

package/dist/types/query.types.d.ts

@@ -0,0 +1,55 @@
+import { StorageRecord, StorageScalar } from "./collection.types.js";
+export type StorageComparison<T = StorageScalar> = {
+  readonly operator: "eq";
+  readonly value: T;
+} | {
+  readonly operator: "ne";
+  readonly value: T;
+} | {
+  readonly operator: "in";
+  readonly value: readonly T[];
+} | {
+  readonly operator: "notIn";
+  readonly value: readonly T[];
+} | {
+  readonly operator: "gt";
+  readonly value: T;
+} | {
+  readonly operator: "gte";
+  readonly value: T;
+} | {
+  readonly operator: "lt";
+  readonly value: T;
+} | {
+  readonly operator: "lte";
+  readonly value: T;
+} | {
+  readonly operator: "exists";
+  readonly value: boolean;
+};
+export type StorageWhere<T extends object> = { readonly [K in keyof T]?: T[K] extends StorageScalar ? StorageComparison<T[K]> : StorageComparison<StorageScalar>; } & {
+  readonly and?: readonly StorageWhere<T>[];
+  readonly or?: readonly StorageWhere<T>[];
+};
+export type StorageOrder<T extends object> = {
+  readonly field: keyof T & string;
+  readonly direction: "asc" | "desc";
+};
+export type StorageQuery<T extends StorageRecord> = {
+  readonly where?: StorageWhere<T>;
+  readonly orderBy?: readonly StorageOrder<T>[];
+  readonly limit?: number;
+  readonly offset?: number;
+};
+export type StorageCursor = {
+  readonly value: string;
+};
+export type StorageCursorQuery<T extends StorageRecord> = Omit<StorageQuery<T>, "offset"> & {
+  readonly first: number;
+  readonly after?: StorageCursor;
+};
+export type StoragePage<T extends StorageRecord> = {
+  readonly items: readonly T[];
+  readonly nextCursor: StorageCursor | null;
+  readonly hasNextPage: boolean;
+};

package/dist/types/schema.types.d.cts

@@ -0,0 +1,16 @@
+import { StorageCollection, StorageRecord } from "./collection.types.cjs";
+export type StorageSchemaRegistry = {
+  readonly collections: readonly StorageCollection<StorageRecord>[];
+};
+export type StorageIndexDefinition = {
+  readonly name: string;
+  readonly collection: string;
+  readonly fields: readonly string[];
+  readonly unique?: boolean;
+  readonly expireAfterSeconds?: number;
+};
+export type StorageSchemaAdapter = {
+  ensureCollection<T extends StorageRecord>(collection: StorageCollection<T>): Promise<void>;
+  ensureIndex(index: StorageIndexDefinition): Promise<void>;
+  listIndexes(collection: string): Promise<readonly StorageIndexDefinition[]>;
+};

package/dist/types/schema.types.d.ts

@@ -0,0 +1,16 @@
+import { StorageCollection, StorageRecord } from "./collection.types.js";
+export type StorageSchemaRegistry = {
+  readonly collections: readonly StorageCollection<StorageRecord>[];
+};
+export type StorageIndexDefinition = {
+  readonly name: string;
+  readonly collection: string;
+  readonly fields: readonly string[];
+  readonly unique?: boolean;
+  readonly expireAfterSeconds?: number;
+};
+export type StorageSchemaAdapter = {
+  ensureCollection<T extends StorageRecord>(collection: StorageCollection<T>): Promise<void>;
+  ensureIndex(index: StorageIndexDefinition): Promise<void>;
+  listIndexes(collection: string): Promise<readonly StorageIndexDefinition[]>;
+};

package/dist/utils/query.utils.cjs

@@ -0,0 +1,44 @@
+const require_storage_errors = require("../errors/storage.errors.cjs");
+// src/utils/query.utils.ts
+const isScalar = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value instanceof Date;
+const isComparison = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const comparison = value;
+	if (![
+		"eq",
+		"ne",
+		"in",
+		"notIn",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"exists"
+	].includes(String(comparison.operator))) return false;
+	if (comparison.operator === "in" || comparison.operator === "notIn") return Array.isArray(comparison.value) && comparison.value.every(isScalar);
+	if (comparison.operator === "exists") return typeof comparison.value === "boolean";
+	return isScalar(comparison.value);
+};
+const validateWhere = (where) => {
+	for (const [field, value] of Object.entries(where)) {
+		if (field === "and" || field === "or") {
+			if (!Array.isArray(value)) throw new require_storage_errors.StorageValidationError(`Query operator "${field}" must be an array.`);
+			for (const nested of value) validateWhere(nested);
+			continue;
+		}
+		if (!isComparison(value)) throw new require_storage_errors.StorageValidationError(`Invalid comparison for field "${field}".`);
+	}
+};
+const validateQuery = (query) => {
+	if (query.limit !== void 0) {
+		if (!Number.isInteger(query.limit) || query.limit < 0) throw new require_storage_errors.StorageValidationError("Query limit must be a non-negative integer.");
+	}
+	if (query.offset !== void 0) {
+		if (!Number.isInteger(query.offset) || query.offset < 0) throw new require_storage_errors.StorageValidationError("Query offset must be a non-negative integer.");
+	}
+	if (query.where) validateWhere(query.where);
+};
+exports.validateQuery = validateQuery;
+exports.validateWhere = validateWhere;
+
+//# sourceMappingURL=query.utils.cjs.map

package/dist/utils/query.utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.utils.cjs","names":["StorageValidationError"],"sources":["../../src/utils/query.utils.ts"],"sourcesContent":["import type { StorageRecord, StorageScalar } from \"../types/collection.types\";\nimport type {\n  StorageComparison,\n  StorageQuery,\n  StorageWhere,\n} from \"../types/query.types\";\nimport { StorageValidationError } from \"../errors/storage.errors\";\n\nconst isScalar = (value: unknown): value is StorageScalar =>\n  value === null ||\n  typeof value === \"string\" ||\n  typeof value === \"number\" ||\n  typeof value === \"boolean\" ||\n  value instanceof Date;\n\nconst isComparison = (value: unknown): value is StorageComparison => {\n  if (!value || typeof value !== \"object\") return false;\n\n  const comparison = value as Record<string, unknown>;\n  const operators = [\n    \"eq\",\n    \"ne\",\n    \"in\",\n    \"notIn\",\n    \"gt\",\n    \"gte\",\n    \"lt\",\n    \"lte\",\n    \"exists\",\n  ];\n\n  if (!operators.includes(String(comparison.operator))) return false;\n\n  if (comparison.operator === \"in\" || comparison.operator === \"notIn\") {\n    return Array.isArray(comparison.value) && comparison.value.every(isScalar);\n  }\n\n  if (comparison.operator === \"exists\") {\n    return typeof comparison.value === \"boolean\";\n  }\n\n  return isScalar(comparison.value);\n};\n\nexport const validateWhere = <T extends object>(\n  where: StorageWhere<T>,\n): void => {\n  for (const [field, value] of Object.entries(where)) {\n    if (field === \"and\" || field === \"or\") {\n      if (!Array.isArray(value)) {\n        throw new StorageValidationError(\n          `Query operator \"${field}\" must be an array.`,\n        );\n      }\n\n      for (const nested of value) {\n        validateWhere(nested as StorageWhere<T>);\n      }\n\n      continue;\n    }\n\n    if (!isComparison(value)) {\n      throw new StorageValidationError(\n        `Invalid comparison for field \"${field}\".`,\n      );\n    }\n  }\n};\n\nexport const validateQuery = <T extends StorageRecord>(\n  query: StorageQuery<T>,\n): void => {\n  if (query.limit !== undefined) {\n    if (!Number.isInteger(query.limit) || query.limit < 0) {\n      throw new StorageValidationError(\n        \"Query limit must be a non-negative integer.\",\n      );\n    }\n  }\n\n  if (query.offset !== undefined) {\n    if (!Number.isInteger(query.offset) || query.offset < 0) {\n      throw new StorageValidationError(\n        \"Query offset must be a non-negative integer.\",\n      );\n    }\n  }\n\n  if (query.where) validateWhere(query.where);\n};\n"],"mappings":";;AAQA,MAAM,YAAY,UAChB,UAAU,QACV,OAAO,UAAU,YACjB,OAAO,UAAU,YACjB,OAAO,UAAU,aACjB,iBAAiB;AAEnB,MAAM,gBAAgB,UAA+C;CACnE,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU,OAAO;CAEhD,MAAM,aAAa;CAanB,IAAI,CAAC;EAXH;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CAGW,CAAC,CAAC,SAAS,OAAO,WAAW,QAAQ,CAAC,GAAG,OAAO;CAE7D,IAAI,WAAW,aAAa,QAAQ,WAAW,aAAa,SAC1D,OAAO,MAAM,QAAQ,WAAW,KAAK,KAAK,WAAW,MAAM,MAAM,QAAQ;CAG3E,IAAI,WAAW,aAAa,UAC1B,OAAO,OAAO,WAAW,UAAU;CAGrC,OAAO,SAAS,WAAW,KAAK;AAClC;AAEA,MAAa,iBACX,UACS;CACT,KAAK,MAAM,CAAC,OAAO,UAAU,OAAO,QAAQ,KAAK,GAAG;EAClD,IAAI,UAAU,SAAS,UAAU,MAAM;GACrC,IAAI,CAAC,MAAM,QAAQ,KAAK,GACtB,MAAM,IAAIA,uBAAAA,uBACR,mBAAmB,MAAM,oBAC3B;GAGF,KAAK,MAAM,UAAU,OACnB,cAAc,MAAyB;GAGzC;EACF;EAEA,IAAI,CAAC,aAAa,KAAK,GACrB,MAAM,IAAIA,uBAAAA,uBACR,iCAAiC,MAAM,GACzC;CAEJ;AACF;AAEA,MAAa,iBACX,UACS;CACT,IAAI,MAAM,UAAU,KAAA,GACd;MAAA,CAAC,OAAO,UAAU,MAAM,KAAK,KAAK,MAAM,QAAQ,GAClD,MAAM,IAAIA,uBAAAA,uBACR,6CACF;CAAA;CAIJ,IAAI,MAAM,WAAW,KAAA,GACf;MAAA,CAAC,OAAO,UAAU,MAAM,MAAM,KAAK,MAAM,SAAS,GACpD,MAAM,IAAIA,uBAAAA,uBACR,8CACF;CAAA;CAIJ,IAAI,MAAM,OAAO,cAAc,MAAM,KAAK;AAC5C"}

package/dist/utils/query.utils.d.cts

@@ -0,0 +1,4 @@
+import { StorageRecord } from "../types/collection.types.cjs";
+import { StorageQuery, StorageWhere } from "../types/query.types.cjs";
+export declare const validateWhere: <T extends object>(where: StorageWhere<T>) => void;
+export declare const validateQuery: <T extends StorageRecord>(query: StorageQuery<T>) => void;

package/dist/utils/query.utils.d.ts

@@ -0,0 +1,4 @@
+import { StorageRecord } from "../types/collection.types.js";
+import { StorageQuery, StorageWhere } from "../types/query.types.js";
+export declare const validateWhere: <T extends object>(where: StorageWhere<T>) => void;
+export declare const validateQuery: <T extends StorageRecord>(query: StorageQuery<T>) => void;

package/dist/utils/query.utils.js

@@ -0,0 +1,43 @@
+import { StorageValidationError } from "../errors/storage.errors.js";
+// src/utils/query.utils.ts
+const isScalar = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value instanceof Date;
+const isComparison = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const comparison = value;
+	if (![
+		"eq",
+		"ne",
+		"in",
+		"notIn",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"exists"
+	].includes(String(comparison.operator))) return false;
+	if (comparison.operator === "in" || comparison.operator === "notIn") return Array.isArray(comparison.value) && comparison.value.every(isScalar);
+	if (comparison.operator === "exists") return typeof comparison.value === "boolean";
+	return isScalar(comparison.value);
+};
+const validateWhere = (where) => {
+	for (const [field, value] of Object.entries(where)) {
+		if (field === "and" || field === "or") {
+			if (!Array.isArray(value)) throw new StorageValidationError(`Query operator "${field}" must be an array.`);
+			for (const nested of value) validateWhere(nested);
+			continue;
+		}
+		if (!isComparison(value)) throw new StorageValidationError(`Invalid comparison for field "${field}".`);
+	}
+};
+const validateQuery = (query) => {
+	if (query.limit !== void 0) {
+		if (!Number.isInteger(query.limit) || query.limit < 0) throw new StorageValidationError("Query limit must be a non-negative integer.");
+	}
+	if (query.offset !== void 0) {
+		if (!Number.isInteger(query.offset) || query.offset < 0) throw new StorageValidationError("Query offset must be a non-negative integer.");
+	}
+	if (query.where) validateWhere(query.where);
+};
+export { validateQuery, validateWhere };
+
+//# sourceMappingURL=query.utils.js.map

package/dist/utils/query.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.utils.js","names":[],"sources":["../../src/utils/query.utils.ts"],"sourcesContent":["import type { StorageRecord, StorageScalar } from \"../types/collection.types\";\nimport type {\n  StorageComparison,\n  StorageQuery,\n  StorageWhere,\n} from \"../types/query.types\";\nimport { StorageValidationError } from \"../errors/storage.errors\";\n\nconst isScalar = (value: unknown): value is StorageScalar =>\n  value === null ||\n  typeof value === \"string\" ||\n  typeof value === \"number\" ||\n  typeof value === \"boolean\" ||\n  value instanceof Date;\n\nconst isComparison = (value: unknown): value is StorageComparison => {\n  if (!value || typeof value !== \"object\") return false;\n\n  const comparison = value as Record<string, unknown>;\n  const operators = [\n    \"eq\",\n    \"ne\",\n    \"in\",\n    \"notIn\",\n    \"gt\",\n    \"gte\",\n    \"lt\",\n    \"lte\",\n    \"exists\",\n  ];\n\n  if (!operators.includes(String(comparison.operator))) return false;\n\n  if (comparison.operator === \"in\" || comparison.operator === \"notIn\") {\n    return Array.isArray(comparison.value) && comparison.value.every(isScalar);\n  }\n\n  if (comparison.operator === \"exists\") {\n    return typeof comparison.value === \"boolean\";\n  }\n\n  return isScalar(comparison.value);\n};\n\nexport const validateWhere = <T extends object>(\n  where: StorageWhere<T>,\n): void => {\n  for (const [field, value] of Object.entries(where)) {\n    if (field === \"and\" || field === \"or\") {\n      if (!Array.isArray(value)) {\n        throw new StorageValidationError(\n          `Query operator \"${field}\" must be an array.`,\n        );\n      }\n\n      for (const nested of value) {\n        validateWhere(nested as StorageWhere<T>);\n      }\n\n      continue;\n    }\n\n    if (!isComparison(value)) {\n      throw new StorageValidationError(\n        `Invalid comparison for field \"${field}\".`,\n      );\n    }\n  }\n};\n\nexport const validateQuery = <T extends StorageRecord>(\n  query: StorageQuery<T>,\n): void => {\n  if (query.limit !== undefined) {\n    if (!Number.isInteger(query.limit) || query.limit < 0) {\n      throw new StorageValidationError(\n        \"Query limit must be a non-negative integer.\",\n      );\n    }\n  }\n\n  if (query.offset !== undefined) {\n    if (!Number.isInteger(query.offset) || query.offset < 0) {\n      throw new StorageValidationError(\n        \"Query offset must be a non-negative integer.\",\n      );\n    }\n  }\n\n  if (query.where) validateWhere(query.where);\n};\n"],"mappings":";;AAQA,MAAM,YAAY,UAChB,UAAU,QACV,OAAO,UAAU,YACjB,OAAO,UAAU,YACjB,OAAO,UAAU,aACjB,iBAAiB;AAEnB,MAAM,gBAAgB,UAA+C;CACnE,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU,OAAO;CAEhD,MAAM,aAAa;CAanB,IAAI,CAAC;EAXH;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CAGW,CAAC,CAAC,SAAS,OAAO,WAAW,QAAQ,CAAC,GAAG,OAAO;CAE7D,IAAI,WAAW,aAAa,QAAQ,WAAW,aAAa,SAC1D,OAAO,MAAM,QAAQ,WAAW,KAAK,KAAK,WAAW,MAAM,MAAM,QAAQ;CAG3E,IAAI,WAAW,aAAa,UAC1B,OAAO,OAAO,WAAW,UAAU;CAGrC,OAAO,SAAS,WAAW,KAAK;AAClC;AAEA,MAAa,iBACX,UACS;CACT,KAAK,MAAM,CAAC,OAAO,UAAU,OAAO,QAAQ,KAAK,GAAG;EAClD,IAAI,UAAU,SAAS,UAAU,MAAM;GACrC,IAAI,CAAC,MAAM,QAAQ,KAAK,GACtB,MAAM,IAAI,uBACR,mBAAmB,MAAM,oBAC3B;GAGF,KAAK,MAAM,UAAU,OACnB,cAAc,MAAyB;GAGzC;EACF;EAEA,IAAI,CAAC,aAAa,KAAK,GACrB,MAAM,IAAI,uBACR,iCAAiC,MAAM,GACzC;CAEJ;AACF;AAEA,MAAa,iBACX,UACS;CACT,IAAI,MAAM,UAAU,KAAA,GACd;MAAA,CAAC,OAAO,UAAU,MAAM,KAAK,KAAK,MAAM,QAAQ,GAClD,MAAM,IAAI,uBACR,6CACF;CAAA;CAIJ,IAAI,MAAM,WAAW,KAAA,GACf;MAAA,CAAC,OAAO,UAAU,MAAM,MAAM,KAAK,MAAM,SAAS,GACpD,MAAM,IAAI,uBACR,8CACF;CAAA;CAIJ,IAAI,MAAM,OAAO,cAAc,MAAM,KAAK;AAC5C"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@puzzle-ui/storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Vendor-neutral storage contracts for Puzzle Auth.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "require": "./dist/testing/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit -p .",
+    "vitest": "node --test",
+    "clean": "rm -rf dist",
+    "prepack": "tsdown"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.4",
+    "bun": "^1.4.4",
+    "tsdown": "^0.23.1",
+    "typescript": "^7.0.2"
+  }
+}