better-auth-elasticsearch 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { elasticsearchAdapter, type ElasticsearchAdapterConfig, } from "./elasticsearch-adapter.js";
 export { migrate, type MigrateOptions, type MigratedModel, type MigrationResult, } from "./migrate.js";
 export { purgeExpired, type PurgeResult } from "./purge.js";
+export type { DuplicateValues } from "./unique-reservations.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,KAAK,0BAA0B,GAChC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,KAAK,0BAA0B,GAChC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/migrate.d.ts

@@ -1,4 +1,5 @@
 import type { MigratedIndex } from "./index-layout.js";
+import type { DuplicateValues } from "./unique-reservations.js";
 /** What migrate() did to one model whose mapping had changed. */
 export interface MigratedModel extends MigratedIndex {
     /** The model's name in the better-auth schema, such as "user". */
@@ -27,6 +28,12 @@ export interface MigrateOptions {
 export interface MigrationResult {
     /** The models that moved to a new index; models already matching are left out. */
     migrated: MigratedModel[];
+    /**
+     * Values of unique fields that more than one row already holds, one entry
+     * per value, naming the rows but not the value. Such rows were written
+     * before the adapter enforced the field; resolve them by hand.
+     */
+    duplicates: DuplicateValues[];
 }
 /** Where the adapter hands migrate() the code that knows its indices. */
 export declare const MIGRATOR: unique symbol;
@@ -45,6 +52,10 @@ export interface AuthWithContext {
  * database is `elasticsearchAdapter(...)`. Reads carry on throughout; writes
  * to a model being moved wait until it is done (see `writeBlockTimeoutMs`).
  * Models already matching are left alone, so running it again is safe.
+ *
+ * Then reserves the values of unique fields for rows that hold no
+ * reservation yet, such as rows written before the adapter enforced them,
+ * and reports values more than one row holds.
  */
 export declare const migrate: (auth: AuthWithContext, options?: MigrateOptions) => Promise<MigrationResult>;
 //# sourceMappingURL=migrate.d.ts.map

package/dist/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,iEAAiE;AACjE,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,yEAAyE;AACzE,eAAO,MAAM,QAAQ,eAA+C,CAAC;AAErE,MAAM,MAAM,QAAQ,GAAG,CACrB,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,KAC9B,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;QAAE,OAAO,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CAClE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,eAAe,EACrB,UAAS,cAAmB,KAC3B,OAAO,CAAC,eAAe,CAczB,CAAC"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,iEAAiE;AACjE,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B;;;;OAIG;IACH,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,yEAAyE;AACzE,eAAO,MAAM,QAAQ,eAA+C,CAAC;AAErE,MAAM,MAAM,QAAQ,GAAG,CACrB,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,KAC9B,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;QAAE,OAAO,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CAClE;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,eAAe,EACrB,UAAS,cAAmB,KAC3B,OAAO,CAAC,eAAe,CAczB,CAAC"}

package/dist/migrate.js

@@ -6,6 +6,10 @@ export const MIGRATOR = Symbol("better-auth-elasticsearch migrator");
  * database is `elasticsearchAdapter(...)`. Reads carry on throughout; writes
  * to a model being moved wait until it is done (see `writeBlockTimeoutMs`).
  * Models already matching are left alone, so running it again is safe.
+ *
+ * Then reserves the values of unique fields for rows that hold no
+ * reservation yet, such as rows written before the adapter enforced them,
+ * and reports values more than one row holds.
  */
 export const migrate = async (auth, options = {}) => {
     const { adapter } = await auth.$context;

package/dist/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAkCA,yEAAyE;AACzE,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,oCAAoC,CAAC,CAAC;AAWrE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAC1B,IAAqB,EACrB,UAA0B,EAAE,EACF,EAAE;IAC5B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC;IACxC,MAAM,QAAQ,GAAI,OAAO,CAAC,OAA+C,EAAE,CACzE,QAAQ,CACe,CAAC;IAC1B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,iHAAiH,CAClH,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;QACd,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,KAAK;QACnD,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,MAAM;KACnD,CAAC,CAAC;AACL,CAAC,CAAC"}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAyCA,yEAAyE;AACzE,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,oCAAoC,CAAC,CAAC;AAWrE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAC1B,IAAqB,EACrB,UAA0B,EAAE,EACF,EAAE;IAC5B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC;IACxC,MAAM,QAAQ,GAAI,OAAO,CAAC,OAA+C,EAAE,CACzE,QAAQ,CACe,CAAC;IAC1B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,iHAAiH,CAClH,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;QACd,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,KAAK;QACnD,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,MAAM;KACnD,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/unique-reservations.d.ts

@@ -0,0 +1,123 @@
+import type { Client } from "@elastic/elasticsearch";
+import type { BetterAuthDBSchema } from "better-auth/db";
+import type { IndexSettings } from "./index-layout.js";
+/**
+ * How long a reservation whose row does not hold its value counts as a write
+ * still in flight. Older, it is left over from a crash and may be taken over,
+ * so a crash blocks a value for at most this long.
+ */
+export declare const GRACE_MS = 120000;
+type Source = Record<string, unknown>;
+/**
+ * A set of fields whose values together must be unique: a field declared
+ * `unique`, or a unique index of the table, which may span several fields.
+ */
+export interface UniqueConstraint {
+    /** The schema field names in index order, joined with "+". */
+    name: string;
+    /** The fields' schema and database names, in index order. */
+    fields: {
+        name: string;
+        dbName: string;
+    }[];
+}
+/** The values a row holds in a constraint's fields, in its field order. */
+export interface HeldValues {
+    constraint: UniqueConstraint;
+    values: unknown[];
+}
+/** The unique values one row's write takes and gives up. */
+export interface RowChange {
+    id: string;
+    claim: HeldValues[];
+    drop?: HeldValues[];
+}
+/** Rows that already hold the same value of a unique field or index. */
+export interface DuplicateValues {
+    /** The model's name in the better-auth schema, such as "user". */
+    model: string;
+    /**
+     * The field's name in the better-auth schema, such as "email", or for an
+     * index over several fields their names joined with "+".
+     */
+    field: string;
+    /** The ids of the rows holding the value. */
+    ids: string[];
+}
+/**
+ * A reservation's `_id`: a hash, so the value itself is never stored. One
+ * field hashes as `[field, value]` however its uniqueness is declared;
+ * several hash as `[fields, values]`, which no single field can collide with.
+ */
+export declare const reservationId: (dbFields: readonly string[], values: readonly unknown[]) => string;
+export declare const duplicateError: (model: string, field: string) => Error;
+export interface ReservationsOptions {
+    client: Client;
+    schema: BetterAuthDBSchema;
+    /** The schema's name for a database model name. */
+    getDefaultModelName: (model: string) => string;
+    /**
+     * Constraints left unenforced, as `model.field`, or `model.fieldA+fieldB`
+     * for an index over several fields, in schema names and index order.
+     */
+    skipUniqueFor: string[];
+    settings: IndexSettings;
+    withRetry: <T>(operation: () => Promise<T>) => Promise<T>;
+}
+/**
+ * Enforces the fields the better-auth schema declares unique and its tables'
+ * unique indexes. Every value of such a field, or combination of values of
+ * such an index, is backed by a reservation document in `<alias>_unique`
+ * whose `_id` derives from the fields and the values, so Elasticsearch refuses a
+ * second one the way it refuses a second row with the same id. Reservations
+ * are only read and written by `_id`, which is real-time, so none of their
+ * writes refresh.
+ */
+export declare const createReservations: ({ client, schema, getDefaultModelName, skipUniqueFor, settings, withRetry, }: ReservationsOptions) => {
+    constraintsOf: (model: string) => UniqueConstraint[];
+    fieldsOf: (model: string, data?: Source) => string[];
+    constrainedFieldIn: (model: string, data: Source) => string | undefined;
+    valuesOf: (model: string, source: Source | undefined) => HeldValues[];
+    changeOf: (model: string, id: string, before: Source | undefined, changes: Source) => RowChange | undefined;
+    claims: (model: string, alias: string) => {
+        /**
+         * Claims the values `changes` take, in one bulk request, and re-stamps
+         * the values they give up so their release can tell whether a later
+         * write re-claimed them. Throws a duplicate key error, having given back
+         * what it created, if another row holds or is writing a value. Called
+         * again when a write reruns, it re-stamps its own claims.
+         */
+        claim(changes: RowChange[]): Promise<void>;
+        /**
+         * After a write of the rows `ids`: releases the values they gave up,
+         * unless a later write re-claimed them since this one re-stamped them.
+         */
+        written(ids: Iterable<string>): Promise<void>;
+        /**
+         * After the rows `ids` were certainly not written: gives back the
+         * reservations this write created for them, unless re-claimed since.
+         */
+        unwritten(ids: Iterable<string>): Promise<void>;
+        /**
+         * After the single row `id` failed to be written with `error`: gives
+         * back the reservations this write created, unless the write may have
+         * landed after all or the row holds the value. A write refused by a
+         * migration's write block keeps them for its rerun.
+         */
+        failed(id: string, error: unknown): Promise<void>;
+        /**
+         * The schema name of a value the row no longer owns, if any. A write
+         * landing later than half the grace period after its claim may have
+         * had one taken over meanwhile; one landing sooner cannot, so it is
+         * not asked.
+         */
+        lost(): Promise<string | undefined>;
+    };
+    release: (model: string, alias: string, rows: {
+        id: string;
+        source: Source | undefined;
+    }[]) => Promise<void>;
+    backfill: (defaultModel: string, alias: string) => Promise<DuplicateValues[]>;
+};
+export {};
+//# sourceMappingURL=unique-reservations.d.ts.map

package/dist/unique-reservations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unique-reservations.d.ts","sourceRoot":"","sources":["../src/unique-reservations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAW,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAQzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,SAAU,CAAC;AAyBhC,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAatC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AAED,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAiDD;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,UAAU,SAAS,MAAM,EAAE,EAC3B,QAAQ,SAAS,OAAO,EAAE,WAQJ,CAAC;AAoCzB,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,OAAO,MAAM,UAGxD,CAAC;AAEJ,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,kBAAkB,CAAC;IAC3B,mDAAmD;IACnD,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C;;;OAGG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC3D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,8EAOhC,mBAAmB;2BA0CU,MAAM;sBAQX,MAAM,SAAS,MAAM;gCAYX,MAAM,QAAQ,MAAM;sBAwF9B,MAAM,UAAU,MAAM,GAAG,SAAS;sBAYlD,MAAM,MACT,MAAM,UACF,MAAM,GAAG,SAAS,WACjB,MAAM,KACd,SAAS,GAAG,SAAS;oBAuBD,MAAM,SAAS,MAAM;QAoGxC;;;;;;WAMG;uBACkB,SAAS,EAAE;QA8GhC;;;WAGG;qBACgB,QAAQ,CAAC,MAAM,CAAC;QAQnC;;;WAGG;uBACkB,QAAQ,CAAC,MAAM,CAAC;QAQrC;;;;;WAKG;mBACc,MAAM,SAAS,OAAO;QAoBvC;;;;;WAKG;gBACW,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;;qBA6BpC,MAAM,SACN,MAAM,QACP;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EAAE;6BA0BpC,MAAM,SACb,MAAM,KACZ,OAAO,CAAC,eAAe,EAAE,CAAC;CAoK9B,CAAC"}