@datar-platform/better-auth-dynamodb 0.1.0-alpha.0 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @datar-platform/better-auth-dynamodb
 
+## 0.1.0
+
+First stable release. No code changes since `0.1.0-alpha.1` — the adapter, the
+built-in single-table store, the query planner, and draining pagination are all
+covered by unit and real-DynamoDB (LocalStack) end-to-end tests. Published with
+npm provenance.
+
+## 0.1.0-alpha.1
+
+### Patch Changes
+
+- Declared `@better-auth/core` as an optional peer dependency so the published
+  type declarations (which reference `@better-auth/core/db`) resolve cleanly
+  under strict package managers.
+- Releases are now published with npm provenance.
+- No runtime behavior changes.
+
 ## 0.1.0-alpha.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,18 +1,268 @@
+import { BetterAuthOptions } from 'better-auth';
+import { AdapterFactory } from 'better-auth/adapters';
+import { DBAdapterDebugLogOption, CleanedWhere } from '@better-auth/core/db/adapter';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { BetterAuthDBSchema } from '@better-auth/core/db';
+import { CreateTableCommandInput, DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
 /**
- * @datar-platform/better-auth-dynamodb
- *
- * A generic DynamoDB adapter for Better Auth. Use the built-in single-table
- * store, or bring your own by implementing {@link DynamoStore}.
- */
-export { dynamoAdapter } from "./adapter.js";
-export type { DynamoAdapterConfig, DynamoStore, QueryPage, StoreItem, } from "./types.js";
-export type { AccessPattern, IndexMap, ModelIndexMap } from "./index-map.js";
-export type { QueryPlan } from "./planner.js";
-export { planQuery } from "./planner.js";
-export { matchesResidual } from "./pagination.js";
-export { createSingleTableStore } from "./stores/default/single-table-store.js";
-export type { SingleTableStoreOptions } from "./stores/default/single-table-store.js";
-export { deriveIndexMap } from "./stores/default/derive-index-map.js";
-export { buildTableDefinition, ensureSchema, generateSchemaFile, } from "./stores/default/schema.js";
-export { assignSlots } from "./stores/default/key-codec.js";
-//# sourceMappingURL=index.d.ts.map
+ * Declarative description of a DynamoDB access pattern (one logical index).
+ *
+ * The adapter never deals in physical `PK`/`SK` strings — it only knows the
+ * *logical* index name and which fields form its partition/sort key. Each store
+ * implementation is responsible for translating a logical index + field values
+ * into a concrete DynamoDB query. This is what lets the exact same generic core
+ * drive both the built-in single-table store and a bring-your-own store (e.g.
+ * one backed by ElectroDB) without either leaking its key encoding upward.
+ */
+interface AccessPattern {
+    /** Logical index name both the planner and the store agree on (e.g. `"byEmail"`). */
+    index: string;
+    /**
+     * Fields that make up the partition key. Every one of these MUST be present as
+     * an equality (`eq`) clause in a `where` for this pattern to be selected.
+     */
+    pk: string[];
+    /**
+     * Ordered fields that make up the sort key. Optional and prefix-satisfiable:
+     * the planner attaches as many leading `sk` fields as the `where` provides
+     * (as `eq` clauses), and leaves the rest to residual in-memory filtering.
+     */
+    sk?: string[];
+}
+/** Ordered list of access patterns for a single model, most specific first. */
+type ModelIndexMap = AccessPattern[];
+/**
+ * Map of model name -> its access patterns. The planner walks a model's
+ * patterns in order and picks the first whose `pk` fields are all present.
+ */
+type IndexMap = Record<string, ModelIndexMap>;
+
+/** A single record as stored/returned. Better Auth handles field-level typing. */
+type StoreItem = Record<string, any>;
+/** One page of a paginated query. `cursor` is opaque and store-defined. */
+interface QueryPage {
+    items: StoreItem[];
+    cursor?: unknown;
+}
+/**
+ * The storage seam. A `DynamoStore` knows how to persist and query records for
+ * a given model; it owns all physical key encoding. The generic adapter core
+ * drives it purely through logical index names + field values, so any store —
+ * the built-in single-table store or a custom one — plugs in the same way.
+ *
+ * Implementations should return the full item (including generated fields) from
+ * `put`/`update` so the adapter can hand it back to Better Auth.
+ */
+interface DynamoStore {
+    /** Persist a new record and return it (with any store-generated fields). */
+    put(model: string, item: StoreItem): Promise<StoreItem>;
+    /** Fetch a single record by its primary `id`, or `null` if absent. */
+    getById(model: string, id: string): Promise<StoreItem | null>;
+    /** Patch the named fields on the record with the given `id` and return the new item. */
+    update(model: string, id: string, patch: StoreItem): Promise<StoreItem | null>;
+    /** Delete the record with the given `id`. No-op if it does not exist. */
+    deleteById(model: string, id: string): Promise<void>;
+    /**
+     * Query a logical index. `key` holds the partition-key field values plus any
+     * leading sort-key field values the caller resolved. Returns one page; the
+     * core drains pages via `cursor` until exhausted.
+     */
+    queryIndex(req: {
+        model: string;
+        index: string;
+        key: StoreItem;
+        limit?: number;
+        cursor?: unknown;
+    }): Promise<QueryPage>;
+    /**
+     * List every record of a model (the substitute for a full table scan when no
+     * index matches a query). Returns one page; the core drains via `cursor`.
+     */
+    listByType(req: {
+        model: string;
+        limit?: number;
+        cursor?: unknown;
+    }): Promise<QueryPage>;
+    /**
+     * Optional fast count. Only used by the core when the query has no residual
+     * (in-memory) predicates. Return `null` to signal "no fast path, fall back to
+     * draining + counting".
+     */
+    count?(req: {
+        model: string;
+        index?: string;
+        key?: StoreItem;
+    }): Promise<number | null>;
+    /**
+     * Optional schema generator, wired to the Better Auth CLI `generate` command.
+     * The built-in store emits a portable CloudFormation template; a custom store
+     * may emit whatever provisioning artifact fits its physical layout.
+     */
+    createSchema?(opts: {
+        file?: string;
+        tables: unknown;
+    }): Promise<{
+        code: string;
+        path: string;
+        overwrite?: boolean;
+    }>;
+}
+/**
+ * Public configuration for {@link dynamoAdapter}.
+ *
+ * Omit `store` to use the built-in single-table store (needs `tableName`).
+ * Omit `indexMap` to auto-derive access patterns from the Better Auth schema
+ * (`unique` fields -> lookup indexes, `references` fields -> by-parent indexes).
+ */
+interface DynamoAdapterConfig {
+    /** Storage backend. Defaults to the built-in single-table store. */
+    store?: DynamoStore;
+    /** Access-pattern map. Defaults to schema-derived patterns. */
+    indexMap?: IndexMap;
+    /** DynamoDB table name (used only by the built-in store). */
+    tableName?: string;
+    /** AWS region (used only by the built-in store). */
+    region?: string;
+    /**
+     * Override the DynamoDB endpoint (used only by the built-in store). Point this
+     * at DynamoDB Local or LocalStack, e.g. `http://localhost:4566`.
+     */
+    endpoint?: string;
+    /** Better Auth debug logging, forwarded to the adapter factory. */
+    debugLogs?: DBAdapterDebugLogOption;
+}
+
+/**
+ * A generic DynamoDB adapter for Better Auth.
+ *
+ * The factory handles field mapping, JSON/date/boolean coercion, ID generation
+ * and `where`-clause normalization; this adapter only implements the raw DB
+ * operations. Those operations are expressed against a pluggable
+ * {@link DynamoStore} and a declarative access-pattern map, so the same core
+ * drives both the built-in single-table store and any custom store.
+ *
+ * @example
+ * ```ts
+ * betterAuth({ database: dynamoAdapter({ tableName: "auth", region: "us-east-1" }) });
+ * ```
+ */
+declare const dynamoAdapter: (config?: DynamoAdapterConfig) => AdapterFactory<BetterAuthOptions>;
+
+/**
+ * A resolved query plan: how the adapter will fetch candidate rows for a
+ * `where` clause before applying any residual (in-memory) filtering.
+ *
+ * - `byId`      — a direct primary-key get (the cheapest path).
+ * - `index`     — a logical index query with a resolved partition/sort key.
+ * - `listByType`— no index matched; list all rows of the model and filter.
+ *
+ * `residual` holds the `where` clauses NOT satisfied by the chosen access path;
+ * they are applied in memory by {@link matchesResidual}.
+ */
+type QueryPlan = {
+    kind: "byId";
+    id: string;
+    residual: CleanedWhere[];
+} | {
+    kind: "index";
+    index: string;
+    key: StoreItem;
+    residual: CleanedWhere[];
+} | {
+    kind: "listByType";
+    residual: CleanedWhere[];
+};
+/**
+ * Choose the most selective access path for `where` against a model's declared
+ * access patterns. Falls back to `listByType` when nothing matches.
+ *
+ * Index selection only ever consumes `eq`/`AND` clauses; everything else (and
+ * any `eq` clause not part of the chosen key) becomes residual.
+ */
+declare function planQuery(model: string, where: CleanedWhere[], indexMap: IndexMap): QueryPlan;
+
+/**
+ * Apply the residual `where` clauses in memory, honoring Better Auth's
+ * connector semantics: all `AND` clauses must match, and — if any `OR` clauses
+ * are present — at least one of them must also match. An empty residual passes.
+ */
+declare function matchesResidual(item: StoreItem, residual: CleanedWhere[]): boolean;
+
+interface SingleTableStoreOptions {
+    /** DynamoDB table name. Falls back to `DYNAMODB_TABLE_NAME`, then `"better-auth"`. */
+    tableName?: string;
+    /** AWS region (passed to the DynamoDB client). */
+    region?: string;
+    /** Endpoint override, e.g. DynamoDB Local or LocalStack (`http://localhost:4566`). */
+    endpoint?: string;
+    /** Resolved logical access-pattern map (derived or user-supplied). */
+    indexMap: IndexMap;
+    /** Pre-built document client (used by tests, e.g. against DynamoDB Local). */
+    documentClient?: DynamoDBDocumentClient;
+}
+/**
+ * A zero-dependency (beyond the AWS SDK) DynamoDB store for Better Auth.
+ *
+ * Uses a single table with a `byType` GSI plus generic lookup GSIs. It owns all
+ * physical key encoding via the key codec, so the generic adapter core drives it
+ * through logical index names only. Works with any Better Auth model or plugin
+ * whose looked-up fields are described by the (typically schema-derived) index
+ * map.
+ */
+declare function createSingleTableStore(opts: SingleTableStoreOptions): DynamoStore;
+
+/**
+ * Derive a logical access-pattern map from a Better Auth schema.
+ *
+ * A single-field lookup index is created for every field that is either:
+ *  - `unique`     (e.g. `user.email`, `session.token`) — direct lookups, or
+ *  - a `references` foreign key (e.g. `account.userId`) — by-parent lookups, or
+ *  - explicitly flagged `index: true`.
+ *
+ * This is what lets the built-in store serve any Better Auth model or plugin
+ * (two-factor, passkey, api-key, …) out of the box: whatever fields the schema
+ * marks as looked-up get an index, with no hand-maintained per-model table.
+ */
+declare function deriveIndexMap(schema: BetterAuthDBSchema): IndexMap;
+
+/** Build the CreateTable input for the built-in store's single-table layout. */
+declare function buildTableDefinition(tableName: string, lookupSlots: number): CreateTableCommandInput;
+/**
+ * Create the table if it does not already exist and wait until it is active.
+ * Idempotent — safe to call at startup or in test `beforeAll` hooks.
+ */
+declare function ensureSchema(opts: {
+    client: DynamoDBClient;
+    tableName: string;
+    lookupSlots: number;
+}): Promise<void>;
+/**
+ * Better Auth CLI `generate` hook: emit a portable CloudFormation template for
+ * the built-in store's table. Table name and lookup-GSI count are configurable
+ * (unlike a hardcoded layout), so the generated stack matches the adapter's
+ * actual access patterns.
+ */
+declare function generateSchemaFile(opts: {
+    tableName: string;
+    lookupSlots: number;
+    file?: string;
+}): {
+    code: string;
+    path: string;
+    overwrite: boolean;
+};
+
+/** Physical slot assignment: model -> (logical index name -> GSI slot number). */
+interface SlotAssignment {
+    slots: Record<string, Record<string, number>>;
+    maxSlots: number;
+}
+/**
+ * Assign each logical index to a physical GSI slot. Because indexes on
+ * different models never coexist on one item, a model's Nth index always maps
+ * to slot N — so the table needs only `max(indexes per model)` lookup GSIs.
+ */
+declare function assignSlots(indexMap: IndexMap): SlotAssignment;
+
+export { type AccessPattern, type DynamoAdapterConfig, type DynamoStore, type IndexMap, type ModelIndexMap, type QueryPage, type QueryPlan, type SingleTableStoreOptions, type StoreItem, assignSlots, buildTableDefinition, createSingleTableStore, deriveIndexMap, dynamoAdapter, ensureSchema, generateSchemaFile, matchesResidual, planQuery };