akanjs 3.1.1-rc.13 → 3.1.1-rc.14

package/document/into.ts

@@ -93,6 +93,14 @@ export type Mdl<
   purgeMany(query: _RawQuery): Promise<number>;
   updateById(id: string, update: DocumentUpdateInput<_RawDoc>, options?: DocumentUpdateOptions): Promise<UpdateResult>;
   removeById(id: string): Promise<UpdateResult>;
+  /**
+   * The same write, over a stored row only when the row matches `where`, a removed row only with `withRemoved`; a free
+   * id is inserted. `modifiedCount` is 0 when the stored row did not match, and `upsertedId` is set on an insert.
+   */
+  upsertById(
+    data: Partial<_RawDoc> & { id: string },
+    options: { where: _RawQuery; withRemoved?: boolean; preserveTimestamps?: boolean },
+  ): Promise<UpdateResult>;
   /**
    * Writes the record as the row under its own id, a new one or in place of the stored one, with no hook: a sync's or a
    * backfill's write, which may run twice. `preserveTimestamps` keeps its `createdAt` and `updatedAt`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.1.1-rc.13",
+  "version": "3.1.1-rc.14",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/service/predefinedAdaptor/sql/SqlDocumentStore.ts

@@ -85,6 +85,13 @@ interface StaleIndex {
 
 type StoredRow = Omit<SqliteDocumentRow, "id">;
 
+interface ProjectedRead {
+  row: ProjectedSqliteDocumentRow;
+  fields: string[];
+}
+
+type StoredRead = StoredRow | ProjectedRead;
+
 const freshDefault = (value: unknown) => (Array.isArray(value) ? [...(value as unknown[])] : value);
 
 export class SqlDocumentStore {
@@ -97,6 +104,7 @@ export class SqlDocumentStore {
   #docPrototype: object | null = null;
   #immutableKeys: string[] | null = null;
   #ensured: Promise<void> | null = null;
+  #warnedUnread = false;
   static readonly #logger = new Logger("SqlDocumentStore");
   /** The row a document was read or last written as. */
   static readonly #storedRow = Symbol("akan.storedRow");
@@ -387,7 +395,10 @@ export class SqlDocumentStore {
     return this.create(data);
   }
 
-  async upsertById(data: DocumentRecord & { id: string }, { preserveTimestamps = false }: UpsertByIdOptions = {}) {
+  async upsertById(
+    data: DocumentRecord & { id: string },
+    { preserveTimestamps = false, where, withRemoved }: UpsertByIdOptions = {},
+  ) {
     if (!isDocumentId(data.id)) throw new Error(`Invalid ID value: ${data.id}`);
     const now = dayjs();
     const keepsCreatedAt = preserveTimestamps && data.createdAt != null;
@@ -398,18 +409,44 @@ export class SqlDocumentStore {
     });
     const row = this.toRow(prepared);
     const kept = keepsCreatedAt ? `"createdAt" = excluded."createdAt", ` : "";
+    const update = `DO UPDATE SET ${kept}"updatedAt" = excluded."updatedAt", "removedAt" = excluded."removedAt", "_doc" = excluded."_doc"`;
+    if (where) return await this.#upsertWhere(data.id, row, update, where, { withRemoved });
     const stored = await this.owner
       .getConnection()
       .prepare(
         `INSERT INTO ${quoteIdent(this.table)} ("id", "createdAt", "updatedAt", "removedAt", "_doc") VALUES (?, ?, ?, ?, ${this.dialect.docValuePlaceholder()})
-           ON CONFLICT("id") DO UPDATE SET ${kept}"updatedAt" = excluded."updatedAt", "removedAt" = excluded."removedAt", "_doc" = excluded."_doc"
-           RETURNING "createdAt"`,
+           ON CONFLICT("id") ${update} RETURNING "createdAt"`,
       )
       .get<{ createdAt: number | string }>(row.id, row.createdAt, row.updatedAt, row.removedAt, row._doc);
     const createdAt = Number(stored?.createdAt ?? row.createdAt);
     return this.#withStoredRow(this.hydrate({ ...prepared, createdAt: dayjs(createdAt) }), { ...row, createdAt });
   }
 
+  async #upsertWhere(id: string, row: StoredRow, update: string, where: DocumentQuery, scope: DocumentScopeOptions) {
+    const { where: condition, params } = this.writeQuery(where, "upsertById", scope);
+    const table = quoteIdent(this.table);
+    const columns = [...BASE_COLUMNS, "_doc"].map(
+      (column) => `${table}.${quoteIdent(column)} AS ${quoteIdent(column)}`,
+    );
+    const written = await this.owner
+      .getConnection()
+      .prepare(
+        this.dialect.upsertRow(
+          this.table,
+          `${update} WHERE EXISTS (SELECT 1 FROM (SELECT ${columns.join(", ")}) AS "stored" WHERE ${condition})`,
+        ),
+      )
+      .get<{ inserted: boolean | number }>(id, row.createdAt, row.updatedAt, row.removedAt, row._doc, ...params);
+    if (!written) return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: null };
+    const inserted = Boolean(Number(written.inserted));
+    return {
+      acknowledged: true,
+      matchedCount: inserted ? 0 : 1,
+      modifiedCount: 1,
+      upsertedId: inserted ? id : null,
+    };
+  }
+
   async update(id: string, patch: DocumentRecord, options: WriteHookOptions = {}) {
     const current = await this.pickByIdForWrite(id);
     return await this.writeUpdatedDocument(id, { ...current, ...patch, id }, current, options);
@@ -599,7 +636,13 @@ export class SqlDocumentStore {
         `SELECT ${this.projectionSql(projection)} ${tail}`,
       ).all<ProjectedSqliteDocumentRow>(...args);
       return rows.map((row) =>
-        this.#readAs(this.hydrate(this.fromProjectedRow(row, projection), undefined, { track: false }), row),
+        this.#readAs(
+          this.#withStoredRow(this.hydrate(this.fromProjectedRow(row, projection), undefined, { track: false }), {
+            row,
+            fields: projection,
+          }),
+          row,
+        ),
       );
     }
     const rows = await this.prepareStmt(`SELECT ${star} ${tail}`).all<SqliteDocumentRow>(...args);
@@ -967,8 +1010,8 @@ export class SqlDocumentStore {
     if (runSaveHooks) await this.runHooks("save", crudType, doc, "pre", previous);
     await this.runHooks(crudType, crudType, doc, "pre", previous);
     const row = this.toRow(doc);
-    const stored = (originalData as Record<symbol, StoredRow | undefined>)[SqlDocumentStore.#storedRow];
-    await this.#writeChanges(id, stored ?? this.toRow(originalData), row, touch);
+    const stored = (originalData as Record<symbol, StoredRead | undefined>)[SqlDocumentStore.#storedRow];
+    await this.#writeChanges(id, stored && !("fields" in stored) ? stored : this.toRow(originalData), row, touch);
     await this.runHooks(crudType, crudType, doc, "post", previous);
     if (runSaveHooks) await this.runHooks("save", crudType, doc, "post", previous);
     return this.#withStoredRow(doc, row);
@@ -1009,10 +1052,19 @@ export class SqlDocumentStore {
   }
 
   #changesOf(doc: DocumentRecord): DocumentRecord {
-    const row = (doc as Record<symbol, StoredRow | undefined>)[SqlDocumentStore.#storedRow];
-    if (!row) return doc;
+    const stored = (doc as Record<symbol, StoredRead | undefined>)[SqlDocumentStore.#storedRow];
+    if (!stored) {
+      this.#warnUnread();
+      return doc;
+    }
     
-    const reread = this.hydrate(this.fromRow({ ...row, id: String(doc.id) }), undefined, { track: false });
+    const reread = this.hydrate(
+      "fields" in stored
+        ? this.fromProjectedRow(stored.row, stored.fields)
+        : this.fromRow({ ...stored, id: String(doc.id) }),
+      undefined,
+      { track: false },
+    );
     const read = SqlDocumentStore.#encodedFields(this.toRow(reread));
     const held = SqlDocumentStore.#encodedFields(this.toRow(doc));
     const changes: DocumentRecord = {};
@@ -1030,7 +1082,17 @@ export class SqlDocumentStore {
     return fields;
   }
 
-  #withStoredRow<Doc extends object>(doc: Doc, row: StoredRow): Doc {
+  #warnUnread() {
+    if (process.env.NODE_ENV === "production" || this.#warnedUnread) return;
+    this.#warnedUnread = true;
+    SqlDocumentStore.#logger.warn(
+      `A ${this.table} document that was never read was saved, so every field it holds was written, undoing what ` +
+        `other writes changed since it was built. Read the document before changing it, or write the fields with ` +
+        `updateById().`,
+    );
+  }
+
+  #withStoredRow<Doc extends object>(doc: Doc, row: StoredRead): Doc {
     Object.defineProperty(doc, SqlDocumentStore.#storedRow, { value: row, configurable: true });
     return doc;
   }
@@ -1210,7 +1272,7 @@ export class SqlDocumentStore {
       },
       refresh: {
         async value(this: DocumentRecord) {
-          const fresh = (await store.pickById(this.id as string)) as DocumentRecord & Record<symbol, StoredRow>;
+          const fresh = (await store.pickById(this.id as string)) as DocumentRecord & Record<symbol, StoredRead>;
           Object.assign(this, fresh);
           Reflect.deleteProperty(this, SqlDocumentStore.#readRemoved);
           return store.#withStoredRow(this, fresh[SqlDocumentStore.#storedRow]);

package/service/predefinedAdaptor/sql/dialect/postgres.ts

@@ -240,6 +240,11 @@ export class PostgresDialect implements SqlDialect {
     }
     return { sql, params };
   }
+  
+  upsertRow(table: string, conflict: string) {
+    return `INSERT INTO ${quoteIdent(table)} ("id", "createdAt", "updatedAt", "removedAt", "_doc") VALUES (?, ?, ?, ?, ${this.docValuePlaceholder()})
+      ON CONFLICT("id") ${conflict} RETURNING ("xmax" = 0) AS "inserted"`;
+  }
   affectedRows(result: unknown): number {
     const row = result as { count?: number } | Array<unknown> | null;
     if (Array.isArray(row)) return (row as { count?: number }).count ?? row.length;

package/service/predefinedAdaptor/sql/dialect/sqlite.ts

@@ -144,6 +144,14 @@ export class SqliteDialect implements SqlDialect {
     if (removed.length) sql = `json_remove(${sql}, ${removed.map((field) => this.#path(field)).join(", ")})`;
     return { sql, params: set.map(([, json]) => json) };
   }
+
+  upsertRow(table: string, conflict: string) {
+    const target = quoteIdent(table);
+    return `WITH "incoming" AS MATERIALIZED (SELECT ? AS "id", ? AS "createdAt", ? AS "updatedAt", ? AS "removedAt", ${this.docValuePlaceholder()} AS "_doc"),
+      "prior" AS MATERIALIZED (SELECT count(*) AS "taken" FROM ${target} WHERE "id" = (SELECT "id" FROM "incoming"))
+      INSERT INTO ${target} ("id", "createdAt", "updatedAt", "removedAt", "_doc") SELECT "incoming".* FROM "incoming", "prior" WHERE true
+      ON CONFLICT("id") ${conflict} RETURNING (SELECT "taken" FROM "prior") = 0 AS "inserted"`;
+  }
   affectedRows(result: unknown): number {
     return Number((result as { changes?: number | bigint } | null)?.changes ?? 0);
   }

package/service/predefinedAdaptor/sql/types.ts

@@ -47,9 +47,11 @@ export interface DatabaseConfig {
   search?: SearchConfig;
 }
 
-export interface UpsertByIdOptions {
+export interface UpsertByIdOptions extends DocumentScopeOptions {
   /** Keep the record's own `createdAt` and `updatedAt`, as a backfill from another system must. */
   preserveTimestamps?: boolean;
+  /** Write over a stored row only when it matches, a removed one only with `withRemoved`; a free id still inserts. */
+  where?: DocumentQuery;
 }
 
 export interface DocumentStore {
@@ -296,6 +298,11 @@ export interface SqlDialect {
   /** The `definition` `indexesOf` reads back for `createIndex(props)`; absent where only the database can tell. */
   indexDefinition?(props: CreateIndexProps): string;
   applyUpdate(acc: string, op: DocumentUpdateOperator, path: string, value: unknown): SqlFrag;
+  /**
+   * One row's `INSERT … ON CONFLICT("id") <conflict>`, binding the id, `createdAt`, `updatedAt`, `removedAt` and
+   * `_doc` before the conflict clause's own values. Each row it wrote returns `"inserted"`, true when no row held the id.
+   */
+  upsertRow(table: string, conflict: string): string;
   /** The stored document with these top-level fields replaced (value as JSON text) and these removed. */
   mergeDocument(set: [field: string, json: string][], removed: string[]): SqlFrag;
   affectedRows(result: unknown): number;

package/types/document/into.d.ts

@@ -59,6 +59,17 @@ export type Mdl<Doc, Raw, _RawDoc = DocumentModel<Raw>, _RawQuery extends Docume
     purgeMany(query: _RawQuery): Promise<number>;
     updateById(id: string, update: DocumentUpdateInput<_RawDoc>, options?: DocumentUpdateOptions): Promise<UpdateResult>;
     removeById(id: string): Promise<UpdateResult>;
+    /**
+     * The same write, over a stored row only when the row matches `where`, a removed row only with `withRemoved`; a free
+     * id is inserted. `modifiedCount` is 0 when the stored row did not match, and `upsertedId` is set on an insert.
+     */
+    upsertById(data: Partial<_RawDoc> & {
+        id: string;
+    }, options: {
+        where: _RawQuery;
+        withRemoved?: boolean;
+        preserveTimestamps?: boolean;
+    }): Promise<UpdateResult>;
     /**
      * Writes the record as the row under its own id, a new one or in place of the stored one, with no hook: a sync's or a
      * backfill's write, which may run twice. `preserveTimestamps` keeps its `createdAt` and `updatedAt`.

package/types/service/predefinedAdaptor/sql/SqlDocumentStore.d.ts

@@ -21,7 +21,7 @@ export declare class SqlDocumentStore {
     }): Promise<any>;
     upsertById(data: DocumentRecord & {
         id: string;
-    }, { preserveTimestamps }?: UpsertByIdOptions): Promise<any>;
+    }, { preserveTimestamps, where, withRemoved }?: UpsertByIdOptions): Promise<any>;
     update(id: string, patch: DocumentRecord, options?: WriteHookOptions): Promise<any>;
     remove(id: string): Promise<any>;
     /** Up to `limit` stored rows after the id `after`, in id order and removed ones included. */

package/types/service/predefinedAdaptor/sql/dialect/postgres.d.ts

@@ -33,5 +33,6 @@ export declare class PostgresDialect implements SqlDialect {
     indexesOf(table: string): SqlFrag;
     applyUpdate(acc: string, op: DocumentUpdateOperator, path: string, value: unknown): SqlFrag;
     mergeDocument(set: [field: string, json: string][], removed: string[]): SqlFrag;
+    upsertRow(table: string, conflict: string): string;
     affectedRows(result: unknown): number;
 }

package/types/service/predefinedAdaptor/sql/dialect/sqlite.d.ts

@@ -29,5 +29,6 @@ export declare class SqliteDialect implements SqlDialect {
     indexDefinition(props: CreateIndexProps): string;
     applyUpdate(acc: string, op: DocumentUpdateOperator, path: string, value: unknown): SqlFrag;
     mergeDocument(set: [field: string, json: string][], removed: string[]): SqlFrag;
+    upsertRow(table: string, conflict: string): string;
     affectedRows(result: unknown): number;
 }

package/types/service/predefinedAdaptor/sql/types.d.ts

@@ -31,9 +31,11 @@ export interface DatabaseConfig {
     postgres?: PostgresDatabaseConfig;
     search?: SearchConfig;
 }
-export interface UpsertByIdOptions {
+export interface UpsertByIdOptions extends DocumentScopeOptions {
     /** Keep the record's own `createdAt` and `updatedAt`, as a backfill from another system must. */
     preserveTimestamps?: boolean;
+    /** Write over a stored row only when it matches, a removed one only with `withRemoved`; a free id still inserts. */
+    where?: DocumentQuery;
 }
 export interface DocumentStore {
     ensure(): Promise<void>;
@@ -296,6 +298,11 @@ export interface SqlDialect {
     /** The `definition` `indexesOf` reads back for `createIndex(props)`; absent where only the database can tell. */
     indexDefinition?(props: CreateIndexProps): string;
     applyUpdate(acc: string, op: DocumentUpdateOperator, path: string, value: unknown): SqlFrag;
+    /**
+     * One row's `INSERT … ON CONFLICT("id") <conflict>`, binding the id, `createdAt`, `updatedAt`, `removedAt` and
+     * `_doc` before the conflict clause's own values. Each row it wrote returns `"inserted"`, true when no row held the id.
+     */
+    upsertRow(table: string, conflict: string): string;
     /** The stored document with these top-level fields replaced (value as JSON text) and these removed. */
     mergeDocument(set: [field: string, json: string][], removed: string[]): SqlFrag;
     affectedRows(result: unknown): number;