@puzzle-ui/storage 0.0.0-stage → 0.5.1

package/README.md

@@ -1,3 +1,56 @@
-# 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 Auth and other packages. This package defines the typed adapter API, query language, migration protocol, and reusable adapter conformance suites; it does not bundle a database implementation.
+
+**Documentation: [puzzle-ui.com/docs/storage](https://puzzle-ui.com/docs/storage)**
+
+## Install
+
+```sh
+npm install @puzzle-ui/storage
+# or: bun add @puzzle-ui/storage
+```
+
+Add a database adapter when you need an implementation: [`@puzzle-ui/storage-d1`](https://puzzle-ui.com/docs/storage#cloudflare-d1-adapter) for Cloudflare D1 or [`@puzzle-ui/storage-mongodb`](https://puzzle-ui.com/docs/storage#mongodb-adapter) for MongoDB.
+
+## Use
+
+Define record types by extending `StorageRecord`, then use an adapter supplied by your application:
+
+```ts
+import type { StorageAdapter, StorageRecord } from "@puzzle-ui/storage";
+
+type Session = StorageRecord & { userId: string; expiresAt: Date };
+
+const storage: StorageAdapter = getConfiguredStorage();
+await storage.registerCollection<Session>({
+  name: "sessions",
+  indexes: [{ name: "by-user", fields: ["userId"] }],
+});
+
+const session = await storage.insert<Session>("sessions", {
+  id: "session_123",
+  userId: "user_123",
+  expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+});
+```
+
+`getConfiguredStorage` is your own adapter factory. Records have an ID, creation/update timestamps, and a revision. The query AST supports comparisons, nested boolean conditions, sorting, offset/limit, and cursor pagination. Conditional writes use expected revisions or update times; adapters advertise guarantees through capability reports. Migrations are explicit and versioned.
+
+## Entry points
+
+- `@puzzle-ui/storage`: storage types, adapter and migration contracts, query validators, and storage errors.
+- `@puzzle-ui/storage/testing`: Bun conformance suites for adapter and migration implementations.
+
+The conformance kit checks core CRUD/query semantics, serialization, revisions, constraints, pagination, batch atomicity, capabilities, and migration behavior. Adapters should run it against isolated test databases before release. `bun run typecheck` also checks the conformance sources with Bun test types.
+
+`StorageSchema` provides an optional type-guard shape, but the shipped D1 and MongoDB adapters do not invoke it automatically; validate untrusted records at your application boundary.
+
+## Development
+
+```sh
+bun run build
+bun run typecheck
+```
+
+See the [storage guide](https://puzzle-ui.com/docs/storage) for contract details, migrations, adapter setup, and custom-adapter guidance.

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,53 @@
 {
   "name": "@puzzle-ui/storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.1",
+  "description": "Vendor-neutral storage contracts for Puzzle Auth.",
+  "homepage": "https://puzzle-ui.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/senorprogramador/puzzle.git"
+  },
+  "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"
+  }
+}