Storage
Vendor-neutral persistence contracts, migrations, adapter conformance testing, and database adapters for Puzzle.
@puzzle-ui/storage defines the persistence contract used by @puzzle-ui/auth and other Puzzle packages. It keeps application storage code independent of a database vendor; separate adapters implement the contract for Cloudflare D1 and MongoDB.
Use the core package to type an adapter or build your own. Add an adapter package when you want a ready-made database implementation. For authentication wiring, see Authentication; for a broader application stack, see Fullstack.
Install
For complete typed CRUD, concurrency handling, MongoDB and D1 configuration, follow the persistent notebook tutorial. The contracts, testing kit and shipped adapters have Stable APIs, with within-major backward-compatibility intent. See the maturity policy. Continue with the Auth tutorial to use the same adapter for identities and sessions.
npm install @puzzle-ui/storageInstall @puzzle-ui/storage-d1 or @puzzle-ui/storage-mongodb alongside the core package to use a built-in adapter. Each adapter declares @puzzle-ui/storage as a dependency.
Quick start
Define a record that extends StorageRecord, then provide a configured adapter. This example uses the vendor-neutral interface; configure a concrete adapter as shown below.
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"] },
{ name: "by-expiry", fields: ["expiresAt"], expireAfterSeconds: 0 },
],
});
const session = await storage.insert<Session>("sessions", {
id: "session_123",
userId: "user_123",
expiresAt: new Date(Date.now() + 60 * 60 * 1000),
});
const current = await storage.findById<Session>("sessions", session.id);getConfiguredStorage is an application-provided factory, not an export from the package. The adapter owns storage I/O and translates the shared types into its database's representation.
Contracts
Records and collections
A StorageRecord has a string id, createdAt, updatedAt, and numeric revision; it may also have revokedAt. Record-specific fields may use strings, numbers, booleans, dates, nulls, or arrays/objects that the adapter can serialize. Successful inserts default missing timestamps to the current time and a missing revision to 1. Successful updates advance the revision and refresh updatedAt.
A collection definition gives a name and may declare a type guard and indexes. An index lists one or more fields and can request uniqueness or TTL expiration. The schema property is typed metadata with a validate type guard; the shipped D1 and MongoDB adapters currently do not call it automatically, so validate untrusted input at your application boundary.
Queries and pagination
Queries use a typed, vendor-neutral AST. Each field condition uses an operator and a value; nested and and or contain more conditions.
const page = await storage.findMany<Session>("sessions", {
where: {
userId: { operator: "eq", value: "user_123" },
expiresAt: { operator: "gt", value: new Date() },
},
orderBy: [{ field: "createdAt", direction: "desc" }],
limit: 25,
});The supported comparison operators are eq, ne, in, notIn, gt, gte, lt, lte, and exists. Queries also support ordering, limit, and offset. Cursor pagination uses findPage with a positive integer first and an opaque after cursor returned from the prior page. Both built-in adapters add a stable ID tie-breaker to cursor ordering.
Conditional writes and capabilities
Pass expectedRevision or expectedUpdatedAt to update or delete to make a write conditional. If a record exists but the condition no longer matches, the adapter reports a StorageConflictError. Use getCapabilities() before relying on optional behavior; capability reports include limitations where relevant.
An adapter may report atomicBatch only when the whole batch is all-or-nothing. A failed operation must not leave partial changes. When the adapter cannot guarantee this, atomicBatch rejects with StorageAtomicityError. Security-sensitive callers should fail closed if the capability they require is unavailable.
| Capability | Meaning |
|---|---|
transactions | Database transactions are available to the adapter. |
atomicBatch | A multi-operation batch is all-or-nothing. |
conditionalWrites | Expected revision or update time can guard a write. |
uniqueConstraints | Unique index guarantees are supported. |
upsert | The adapter supports the shared upsert operation. |
cursorPagination | Cursor-based pages are supported. |
migrations | Durable migrations are supported. |
ttlIndexes | Index-based record expiration is supported. |
Migrations
Migrations are explicit and versioned. Ordinary reads and writes never run them implicitly. A migration has a stable id, integer version, description, and asynchronous up function. Its context exposes one operation runner for creating or dropping a collection or index.
import type { StorageMigration } from "@puzzle-ui/storage";
const initialSchema: StorageMigration = {
id: "2026-01-sessions",
version: 1,
description: "Create the sessions collection and user index",
up: async ({ execute }) => {
await execute({ type: "createCollection", collection: "sessions" });
await execute({
type: "createIndex",
collection: "sessions",
name: "by-user",
fields: ["userId"],
});
},
};
const result = await migrationAdapter.runMigrations([initialSchema], {
targetVersion: 1,
});Migration adapters persist each migration's status and serialize concurrent runners using a database lock. Completed migrations are skipped; failed migrations are recorded and may be retried. targetVersion limits which versions run, and dryRun reports the versions that would be applied without executing them. Migration operations are not automatically wrapped in one transaction: make each migration safe to retry, and take care with destructive drops.
Conformance testing kit
The @puzzle-ui/storage/testing subpath exports reusable Bun test suites for adapter implementations. Give the suite a factory that creates an adapter against a clean test database and a reset function that isolates each case.
import { runStorageAdapterConformance } from "@puzzle-ui/storage/testing";
runStorageAdapterConformance({
createAdapter: async () => makeTestAdapter(),
reset: async () => resetTestDatabase(),
});The suite covers capability reporting, CRUD and upsert, query and serialization behavior (including dates and nulls), cursor pagination, conditional writes and revision conflicts, uniqueness, and atomic-batch rollback. Use runStorageMigrationConformance with a fixture containing createMigrationAdapter and reset callbacks for migration ordering, status, failure/retry, target versions, and concurrent runners. The fixture types allow an optional dispose callback; manage connection and container cleanup in your own test lifecycle.
Cloudflare D1 adapter
@puzzle-ui/storage-d1 implements the shared storage and migration interfaces using a Cloudflare D1 database binding. Install it with the core package:
npm install @puzzle-ui/storage @puzzle-ui/storage-d1The adapter accepts the D1 binding through its structural D1DatabaseLike type; it does not create or manage the Cloudflare database itself. Add a binding to wrangler.toml (or the equivalent wrangler.jsonc configuration):
[[d1_databases]]
binding = "DB"
database_name = "app-db"
database_id = "<database-id>"Pass env.DB to D1StorageAdapter from your Worker. The example expects a Worker environment with a D1 binding named DB.
import { D1StorageAdapter, D1StorageMigrationAdapter } from "@puzzle-ui/storage-d1";
import type { D1DatabaseLike } from "@puzzle-ui/storage-d1";
export default {
async fetch(_request: Request, env: { DB: D1DatabaseLike }) {
const storage = new D1StorageAdapter({ database: env.DB });
const migrations = new D1StorageMigrationAdapter({ database: env.DB });
await migrations.runMigrations([initialSchema]);
await storage.registerCollection({ name: "sessions" });
return new Response("Storage is ready");
},
};Use one-time deployment or startup orchestration for runMigrations; avoid running the migration list on every request. D1's migration adapter maintains its own prefixed migration and lock tables. These are adapter-managed migrations—not Wrangler's SQL migration directory or wrangler d1 migrations commands. Wrangler still manages the database binding and local/remote database lifecycle. registerCollection creates the prefixed table and any declared indexes if they do not exist.
The default table prefix is puzzle_; set tablePrefix to change it. D1 stores record-specific fields as JSON and keeps IDs, timestamps, and revisions in columns. It supports the shared query operators, conditional writes, cursor pagination, unique indexes, migrations, and atomic batches. D1 reports transactions and atomic batches as supported through its batch API; it does not provide TTL indexes, so schedule expiration cleanup in your application or a Worker cron job. Configure a distinct prefix if multiple adapters share a database and need separate table namespaces.
D1 migration options are database, tablePrefix, and lockDurationMs (default: 600,000 milliseconds). The adapter validates table and field identifiers used to build SQL. Avoid using dynamic or untrusted values as collection, index, or field names.
MongoDB adapter
@puzzle-ui/storage-mongodb implements the same contracts using the official MongoDB Node.js driver. Install the package and its core contract:
npm install @puzzle-ui/storage @puzzle-ui/storage-mongodbConnect a MongoClient, obtain a Db, and pass both to MongoStorageAdapter when you need multi-document transactions.
import { MongoClient } from "mongodb";
import { MongoStorageAdapter, MongoStorageMigrationAdapter } from "@puzzle-ui/storage-mongodb";
const client = new MongoClient(process.env.MONGODB_URI!);
await client.connect();
const database = client.db("app");
const storage = new MongoStorageAdapter({
database,
client,
transactionsEnabled: true,
});
const migrations = new MongoStorageMigrationAdapter({ database });
await migrations.runMigrations([initialSchema]);
await storage.registerCollection({
name: "sessions",
indexes: [
{ name: "by-user", fields: ["userId"] },
{ name: "expire-at", fields: ["expiresAt"], expireAfterSeconds: 0 },
],
});The default collection prefix is puzzle_. Set collectionPrefix to use another namespace. Collection registration creates the collection if needed, then creates the declared indexes. Index fields are ascending; unique requests a unique index and expireAfterSeconds creates a MongoDB TTL index. For TTL to remove a document, its indexed field must contain a supported BSON date. TTL deletion is asynchronous and should not be treated as an exact-time authorization check; check expiry in application logic too.
MongoDB reports transactions and atomic batches as unavailable by default. To enable them, pass a MongoClient, set transactionsEnabled: true, and use a replica set or sharded deployment that supports transactions. The flag is an explicit opt-in; enabling it does not configure the server. Without both client and flag, atomicBatch rejects with StorageAtomicityError. Other capabilities include conditional writes, unique constraints, upsert, cursor pagination, migrations, and TTL indexes.
The migration adapter creates prefixed migration and lock collections and an expiration index for lock cleanup. Its options are database, collectionPrefix, and lockDurationMs (default: 600,000 milliseconds). Close the client when your application shuts down.
Writing a custom adapter
Implement StorageAdapter for CRUD, query, pagination, and batching. Implement StorageMigrationAdapter separately when migrations are supported. A production adapter should:
- Preserve date, null, and query semantics across the vendor translation.
- Increment revisions on updates and honor conditional writes.
- Report only capabilities it can guarantee; never claim atomicity without rollback semantics.
- Persist migration state, order by version, and prevent concurrent runners from applying the same migration twice.
- Run the shared test suites from the
./testingsubpath against an isolated test database.
The StorageSchemaAdapter interface describes collection and index discovery operations. The built-in adapters currently expose registration directly on StorageAdapter; they do not implement this separate schema adapter interface.
API reference
Storage methods
| Method | Type | Default | Description |
|---|---|---|---|
registerCollection | (collection) => Promise<void> | — | Ensure the collection and declared indexes exist. |
findById | (collection, id) => Promise<T | null> | — | Read one record by ID. |
findOne | (collection, query) => Promise<T | null> | — | Read the first matching record. |
findMany | (collection, query?) => Promise<readonly T[]> | Empty query | Read matching records. |
findPage | (collection, query) => Promise<StoragePage<T>> | — | Read a cursor page. |
insert | (collection, record) => Promise<T> | — | Insert a record. |
upsert | (collection, query, record) => Promise<T> | — | Update a match or insert when none exists. |
update | (collection, id, changes, condition?) => Promise<T | null> | — | Update one record; returns null when absent. |
updateMany | (collection, query, changes) => Promise<number> | — | Update matching records and return the count. |
delete | (collection, id, condition?) => Promise<boolean> | — | Delete one record and report whether it existed. |
deleteMany | (collection, query) => Promise<number> | — | Delete matching records and return the count. |
exists | (collection, query) => Promise<boolean> | — | Check whether a match exists. |
count | (collection, query?) => Promise<number> | Empty query | Count matching records. |
atomicBatch | (operations) => Promise<StorageBatchResult<T>> | — | Execute insert, update, and delete operations atomically when supported. |
getCapabilities | () => StorageCapabilityReport | — | Inspect support and adapter limitations. |
Options
| Option | Type | Default | Description |
|---|---|---|---|
StorageAdapterOptions.requireAtomicBatch | boolean | undefined | Optional shared flag; the core package does not itself enforce this value. |
D1StorageAdapterOptions.database | D1DatabaseLike | Required | D1 database binding. |
D1StorageMigrationOptions.database | D1DatabaseLike | Required | D1 database binding for migrations. |
StorageMigrationOptions.targetVersion | number | Latest provided version | Do not run versions above this value. |
StorageMigrationOptions.dryRun | boolean | false | Report migrations that would apply without running them. |
D1StorageAdapterOptions.tablePrefix | string | "puzzle_" | Prefix D1 collection table names. |
D1StorageMigrationOptions.tablePrefix | string | "puzzle_" | Prefix D1 migration and lock table names. |
D1StorageMigrationOptions.lockDurationMs | number | 600000 | Lock wait/lease duration in milliseconds. |
MongoStorageAdapterOptions.database | Db | Required | MongoDB database handle. |
MongoStorageAdapterOptions.client | MongoClient | undefined | Client required with transactionsEnabled to enable transactions. |
MongoStorageMigrationOptions.database | Db | Required | MongoDB database handle for migrations. |
MongoStorageAdapterOptions.collectionPrefix | string | "puzzle_" | Prefix MongoDB collection names. |
MongoStorageAdapterOptions.transactionsEnabled | boolean | false | Opt in to transactions and atomic batches when a client is provided. |
MongoStorageMigrationOptions.collectionPrefix | string | "puzzle_" | Prefix migration and lock collection names. |
MongoStorageMigrationOptions.lockDurationMs | number | 600000 | Lock wait/lease duration in milliseconds. |
Exports
| Entry point | Public exports |
|---|---|
@puzzle-ui/storage | Types: StorageScalar, StorageRecord, StorageCollectionName, StorageField, StorageCollectionOptions, StorageCollection, StorageSchema, StorageIndex, StorageComparison, StorageWhere, StorageOrder, StorageQuery, StorageCursor, StorageCursorQuery, StoragePage, StorageCapabilities, StorageCapability, StorageCapabilityReport, StorageInsert, StorageUpdate, StorageCondition, StorageBatchOperation, StorageBatchResult, StorageAdapterOptions, StorageAdapter, StorageMigrationContext, StorageMigrationOperation, StorageMigration, StorageMigrationStatus, StorageMigrationRecord, StorageMigrationResult, StorageMigrationOptions, StorageMigrationAdapter, StorageSchemaRegistry, StorageIndexDefinition, StorageSchemaAdapter. Runtime exports: DEFAULT_STORAGE_CAPABILITIES, StorageError, StorageCapabilityError, StorageConflictError, StorageDuplicateError, StorageValidationError, StorageAtomicityError, validateQuery, validateWhere. |
@puzzle-ui/storage/testing | runStorageAdapterConformance, runStorageMigrationConformance. |
@puzzle-ui/storage-d1 | D1StorageAdapter, D1StorageMigrationAdapter, D1DatabaseLike, D1PreparedStatementLike, D1ResultLike, D1StorageAdapterOptions, D1StorageMigrationOptions. |
@puzzle-ui/storage-mongodb | MongoStorageAdapter, MongoStorageMigrationAdapter, MongoStorageAdapterOptions, MongoStorageMigrationOptions. |
Related packages
- Authentication uses the storage contracts for persistence.
- Fullstack brings Puzzle's application packages together.