@starkeep/storage-sqlite 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @starkeep/storage-sqlite
2
2
 
3
- SQLite implementation of `DatabaseAdapter` using the built-in `node:sqlite` module (Node.js 22+). No native compilation dependencies required.
3
+ SQLite implementation of `DatabaseAdapter` using the built-in `node:sqlite` module. No native compilation dependencies required.
4
4
 
5
5
  ## Installation
6
6
 
@@ -8,7 +8,7 @@ SQLite implementation of `DatabaseAdapter` using the built-in `node:sqlite` modu
8
8
  pnpm add @starkeep/storage-sqlite
9
9
  ```
10
10
 
11
- Requires Node.js 22 or later for `node:sqlite` support.
11
+ Requires Node.js 24 or later, the version the rest of Starkeep requires.
12
12
 
13
13
  ## Usage
14
14
 
@@ -63,6 +63,13 @@ declare class SqliteDatabaseAdapter implements DatabaseAdapter {
63
63
  private getRow;
64
64
  private allRows;
65
65
  put(record: DataRecord): Promise<void>;
66
+ putSnapshot(record: DataRecord): Promise<boolean>;
67
+ /**
68
+ * One upsert statement. With `onlyIfNewer` an existing row is replaced only
69
+ * by a strictly later `updated_at` (see `DatabaseAdapter.putSnapshot`), and
70
+ * the result says whether a row was written.
71
+ */
72
+ private upsertRecord;
66
73
  get(id: StarkeepId): Promise<DataRecord | null>;
67
74
  delete(id: StarkeepId, hlc: HLCTimestamp): Promise<void>;
68
75
  getNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
@@ -102,7 +109,7 @@ declare class SqliteDatabaseAdapter implements DatabaseAdapter {
102
109
  * query draws.
103
110
  */
104
111
  findByLabel(query: FindByLabelQuery): Promise<FindByLabelResult>;
105
- putLabel(label: RecordLabel): Promise<void>;
112
+ putLabel(label: RecordLabel): Promise<boolean>;
106
113
  getLabel(recordId: StarkeepId, appId: string, key: string, value: string): Promise<RecordLabel | null>;
107
114
  queryLabels(query: {
108
115
  limit?: number;
@@ -63,6 +63,13 @@ declare class SqliteDatabaseAdapter implements DatabaseAdapter {
63
63
  private getRow;
64
64
  private allRows;
65
65
  put(record: DataRecord): Promise<void>;
66
+ putSnapshot(record: DataRecord): Promise<boolean>;
67
+ /**
68
+ * One upsert statement. With `onlyIfNewer` an existing row is replaced only
69
+ * by a strictly later `updated_at` (see `DatabaseAdapter.putSnapshot`), and
70
+ * the result says whether a row was written.
71
+ */
72
+ private upsertRecord;
66
73
  get(id: StarkeepId): Promise<DataRecord | null>;
67
74
  delete(id: StarkeepId, hlc: HLCTimestamp): Promise<void>;
68
75
  getNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
@@ -102,7 +109,7 @@ declare class SqliteDatabaseAdapter implements DatabaseAdapter {
102
109
  * query draws.
103
110
  */
104
111
  findByLabel(query: FindByLabelQuery): Promise<FindByLabelResult>;
105
- putLabel(label: RecordLabel): Promise<void>;
112
+ putLabel(label: RecordLabel): Promise<boolean>;
106
113
  getLabel(recordId: StarkeepId, appId: string, key: string, value: string): Promise<RecordLabel | null>;
107
114
  queryLabels(query: {
108
115
  limit?: number;
package/dist/index.cjs CHANGED
@@ -67,6 +67,8 @@ function recordToRow(record) {
67
67
  mime_type: record.mimeType,
68
68
  size_bytes: record.sizeBytes,
69
69
  original_filename: record.originalFilename,
70
+ original_created_at: record.originalCreatedAt ?? null,
71
+ original_updated_at: record.originalUpdatedAt ?? null,
70
72
  origin_app_id: record.originAppId,
71
73
  parent_id: record.parentId,
72
74
  stand_in_role: record.standInRole,
@@ -90,6 +92,8 @@ function rowToRecord(row) {
90
92
  mimeType: row.mime_type,
91
93
  sizeBytes: row.size_bytes,
92
94
  originalFilename: row.original_filename,
95
+ originalCreatedAt: row.original_created_at ?? null,
96
+ originalUpdatedAt: row.original_updated_at ?? null,
93
97
  originAppId: row.origin_app_id,
94
98
  parentId: row.parent_id ? (0, import_protocol_primitives.createStarkeepId)(row.parent_id) : null,
95
99
  standInRole: (0, import_protocol_primitives.isStandInRole)(row.stand_in_role) ? row.stand_in_role : null,
@@ -142,12 +146,18 @@ function applyLocalSchemaDdl(db) {
142
146
  db.exec("PRAGMA foreign_keys = ON");
143
147
  applyConnectionPragmas(db);
144
148
  db.exec(
145
- compiler.schema.createTable("shared_records").ifNotExists().addColumn("id", "text", (c) => c.primaryKey()).addColumn("type", "text", (c) => c.notNull()).addColumn("created_at", "text", (c) => c.notNull()).addColumn("updated_at", "text", (c) => c.notNull()).addColumn("node_id", "text", (c) => c.notNull()).addColumn("deleted_at", "text").addColumn("version", "integer", (c) => c.notNull().defaultTo(1)).addColumn("content_hash", "text", (c) => c.notNull()).addColumn("object_storage_key", "text", (c) => c.notNull()).addColumn("mime_type", "text").addColumn("size_bytes", "integer", (c) => c.notNull()).addColumn("original_filename", "text").addColumn("origin_app_id", "text", (c) => c.notNull()).addColumn("parent_id", "text").addColumn(
149
+ compiler.schema.createTable("shared_records").ifNotExists().addColumn("id", "text", (c) => c.primaryKey()).addColumn("type", "text", (c) => c.notNull()).addColumn("created_at", "text", (c) => c.notNull()).addColumn("updated_at", "text", (c) => c.notNull()).addColumn("node_id", "text", (c) => c.notNull()).addColumn("deleted_at", "text").addColumn("version", "integer", (c) => c.notNull().defaultTo(1)).addColumn("content_hash", "text", (c) => c.notNull()).addColumn("object_storage_key", "text", (c) => c.notNull()).addColumn("mime_type", "text").addColumn("size_bytes", "integer", (c) => c.notNull()).addColumn("original_filename", "text").addColumn("original_created_at", "text").addColumn("original_updated_at", "text").addColumn("origin_app_id", "text", (c) => c.notNull()).addColumn("parent_id", "text").addColumn(
146
150
  "stand_in_role",
147
151
  "text",
148
152
  (c) => c.check(import_kysely2.sql`stand_in_role IN ('canonical', 'smaller')`)
149
153
  ).addColumn("fidelity", "integer").addColumn("canonical_threshold", "integer").addColumn("self_canonical", "integer").addColumn("stand_in_slot", "text").compile().sql
150
154
  );
155
+ const recordColumns = db.prepare("SELECT name FROM pragma_table_info('shared_records')").all();
156
+ for (const column of ["original_created_at", "original_updated_at"]) {
157
+ if (!recordColumns.some((c) => c.name === column)) {
158
+ db.exec(compiler.schema.alterTable("shared_records").addColumn(column, "text").compile().sql);
159
+ }
160
+ }
151
161
  const sharedRecordsIndexes = [
152
162
  compiler.schema.createIndex("idx_shared_records_type").ifNotExists().on("shared_records").column("type"),
153
163
  compiler.schema.createIndex("idx_shared_records_node_watermark").ifNotExists().on("shared_records").columns(["node_id", "updated_at"]),
@@ -354,16 +364,32 @@ var SqliteDatabaseAdapter = class {
354
364
  return this.getDatabase().prepare(sql5).all(...params.map(toSqliteParam));
355
365
  }
356
366
  async put(record) {
367
+ this.upsertRecord(record, false);
368
+ }
369
+ async putSnapshot(record) {
370
+ return this.upsertRecord(record, true);
371
+ }
372
+ /**
373
+ * One upsert statement. With `onlyIfNewer` an existing row is replaced only
374
+ * by a strictly later `updated_at` (see `DatabaseAdapter.putSnapshot`), and
375
+ * the result says whether a row was written.
376
+ */
377
+ upsertRecord(record, onlyIfNewer) {
357
378
  const row = recordToRow(record);
358
379
  const updateColumns = Object.keys(row).filter((column) => column !== "id");
359
- const query = compiler.insertInto("shared_records").values({ ...row }).onConflict(
360
- (oc) => oc.column("id").doUpdateSet(
380
+ const query = compiler.insertInto("shared_records").values({ ...row }).onConflict((oc) => {
381
+ const update = oc.column("id").doUpdateSet(
361
382
  (eb) => Object.fromEntries(
362
383
  updateColumns.map((column) => [column, eb.ref(`excluded.${column}`)])
363
384
  )
364
- )
365
- ).compile();
366
- this.runStmt(query.sql, ...query.parameters);
385
+ );
386
+ return onlyIfNewer ? update.where(
387
+ import_kysely3.sql.ref("excluded.updated_at"),
388
+ ">",
389
+ import_kysely3.sql.ref("shared_records.updated_at")
390
+ ) : update;
391
+ }).returning("id").compile();
392
+ return this.allRows(query.sql, ...query.parameters).length > 0;
367
393
  }
368
394
  async get(id) {
369
395
  const query = compiler.selectFrom("shared_records").selectAll().where("id", "=", id).compile();
@@ -627,7 +653,7 @@ var SqliteDatabaseAdapter = class {
627
653
  // ---- Label sync ---------------------------------------------------------
628
654
  async putLabel(label) {
629
655
  const query = (0, import_storage_adapter4.buildLabelSnapshotUpsert)(compiler, LABELS, label);
630
- this.runStmt(query.sql, ...query.parameters);
656
+ return this.allRows(query.sql, ...query.parameters).length > 0;
631
657
  }
632
658
  async getLabel(recordId, appId, key, value) {
633
659
  const query = (0, import_storage_adapter4.buildGetLabel)(compiler, LABELS, recordId, appId, key, value);
@@ -797,9 +823,10 @@ var import_kysely4 = require("kysely");
797
823
  var import_protocol_primitives5 = require("@starkeep/protocol-primitives");
798
824
  var import_shared_space_api2 = require("@starkeep/shared-space-api");
799
825
  var import_storage_adapter5 = require("@starkeep/storage-adapter");
800
- function runCompiled(db, compiled) {
801
- db.prepare(compiled.sql).run(...compiled.parameters.map(toSqliteParam));
826
+ function countCompiled(db, compiled) {
827
+ return allCompiled(db, compiled).length;
802
828
  }
829
+ var WRITTEN = import_kysely4.sql`1`.as("written");
803
830
  function allCompiled(db, compiled) {
804
831
  return db.prepare(compiled.sql).all(...compiled.parameters.map(toSqliteParam));
805
832
  }
@@ -810,7 +837,7 @@ var SqliteAppSyncableApplier = class {
810
837
  }
811
838
  db;
812
839
  namespace;
813
- apply(entry) {
840
+ apply(entry, conditions) {
814
841
  const ns = this.namespace.get(entry.appId);
815
842
  if (!ns) {
816
843
  throw new Error(`SqliteAppSyncableApplier: app "${entry.appId}" not installed`);
@@ -824,42 +851,52 @@ var SqliteAppSyncableApplier = class {
824
851
  (0, import_shared_space_api2.requireWellFormedFileIndexRow)(entry);
825
852
  const fullName = appSyncableTableName(entry.appId, entry.table);
826
853
  const { pkColumns } = tableInfo;
854
+ let changes;
827
855
  if (entry.op === "insert") {
828
- this.applyInsert(fullName, pkColumns, entry);
856
+ changes = this.applyInsert(fullName, pkColumns, entry, conditions);
829
857
  } else if (entry.op === "update") {
830
- this.applyUpdate(fullName, pkColumns, entry);
858
+ changes = this.applyUpdate(fullName, pkColumns, entry, conditions);
831
859
  } else {
832
- this.applyDelete(fullName, pkColumns, entry);
860
+ changes = this.applyDelete(fullName, pkColumns, entry, conditions);
833
861
  }
862
+ if (changes > 0 || conditions === void 0) return { changes };
863
+ const probe = this.selectRows((0, import_storage_adapter5.buildRowProbe)(compiler, fullName, (0, import_storage_adapter5.probeKeyFor)(entry, pkColumns)))[0];
864
+ return { changes: 0, skipped: (0, import_storage_adapter5.classifySkippedWrite)(entry.op, probe, conditions) };
834
865
  }
835
- applyInsert(fullName, pkColumns, entry) {
866
+ applyInsert(fullName, pkColumns, entry, conditions) {
836
867
  const row = withNodeId(entry.row ?? {}, entry);
837
868
  const cols = Object.keys(row);
838
- if (cols.length === 0) return;
869
+ if (cols.length === 0) return 0;
870
+ if (conditions?.ifAbsent) {
871
+ (0, import_storage_adapter5.requireInsertKey)(entry, pkColumns);
872
+ return countCompiled(
873
+ this.db,
874
+ compiler.insertInto(fullName).values({ ...row }).onConflict((oc) => oc.columns(pkColumns).doNothing()).returning(WRITTEN).compile()
875
+ );
876
+ }
839
877
  const updateCols = cols.filter((c) => !pkColumns.includes(c));
840
878
  if (pkColumns.length === 0 || updateCols.length === 0) {
841
- runCompiled(
879
+ return countCompiled(
842
880
  this.db,
843
- compiler.insertInto(fullName).orIgnore().values({ ...row }).compile()
881
+ compiler.insertInto(fullName).orIgnore().values({ ...row }).returning(WRITTEN).compile()
844
882
  );
845
- return;
846
883
  }
847
- runCompiled(
884
+ return countCompiled(
848
885
  this.db,
849
886
  compiler.insertInto(fullName).values({ ...row }).onConflict(
850
887
  (oc) => oc.columns(pkColumns).doUpdateSet(
851
888
  (eb) => Object.fromEntries(updateCols.map((c) => [c, eb.ref(`excluded.${c}`)]))
852
889
  ).where(import_kysely4.sql.ref("excluded.updated_at"), ">", import_kysely4.sql.ref(`${fullName}.updated_at`))
853
- ).compile()
890
+ ).returning(WRITTEN).compile()
854
891
  );
855
892
  }
856
- applyUpdate(fullName, pkColumns, entry) {
893
+ applyUpdate(fullName, pkColumns, entry, conditions) {
857
894
  const rawPatch = entry.row ?? {};
858
895
  const patch = rawPatch["updated_at"] ? withNodeId(rawPatch, entry) : rawPatch;
859
896
  const where = (0, import_storage_adapter5.requireKeyedWhere)(entry, "update", pkColumns);
860
897
  const patchCols = Object.keys(patch);
861
898
  const whereCols = Object.keys(where);
862
- if (patchCols.length === 0) return;
899
+ if (patchCols.length === 0) return 0;
863
900
  const incomingUpdatedAt = patch["updated_at"];
864
901
  let query = compiler.updateTable(fullName).set({ ...patch });
865
902
  for (const c of whereCols) {
@@ -870,9 +907,13 @@ var SqliteAppSyncableApplier = class {
870
907
  (eb) => eb.or([eb("updated_at", "is", null), eb("updated_at", "<", incomingUpdatedAt)])
871
908
  );
872
909
  }
873
- runCompiled(this.db, query.compile());
910
+ query = query.where("deleted_at", "is", null);
911
+ if (conditions?.ifUpdatedAt !== void 0) {
912
+ query = query.where("updated_at", "=", conditions.ifUpdatedAt);
913
+ }
914
+ return countCompiled(this.db, query.returning(WRITTEN).compile());
874
915
  }
875
- applyDelete(fullName, pkColumns, entry) {
916
+ applyDelete(fullName, pkColumns, entry, conditions) {
876
917
  const where = (0, import_storage_adapter5.requireKeyedWhere)(entry, "delete", pkColumns);
877
918
  const whereCols = Object.keys(where);
878
919
  const incomingUpdatedAt = entry.row?.["updated_at"];
@@ -881,22 +922,25 @@ var SqliteAppSyncableApplier = class {
881
922
  if (carriesFullRow) {
882
923
  const row = withNodeId({ ...entry.row, updated_at: ts, deleted_at: ts }, entry);
883
924
  const updateCols = Object.keys(row).filter((c) => !pkColumns.includes(c));
884
- runCompiled(
925
+ return countCompiled(
885
926
  this.db,
886
927
  compiler.insertInto(fullName).values({ ...row }).onConflict(
887
928
  (oc) => oc.columns(pkColumns).doUpdateSet(
888
929
  (eb) => Object.fromEntries(updateCols.map((c) => [c, eb.ref(`excluded.${c}`)]))
889
930
  ).where(import_kysely4.sql.ref("excluded.updated_at"), ">", import_kysely4.sql.ref(`${fullName}.updated_at`))
890
- ).compile()
931
+ ).returning(WRITTEN).compile()
891
932
  );
892
- return;
893
933
  }
894
934
  let query = compiler.updateTable(fullName).set({ deleted_at: ts, updated_at: ts, node_id: nodeIdOf(ts, entry) });
895
935
  for (const c of whereCols) {
896
936
  query = query.where(c, "=", where[c]);
897
937
  }
898
938
  query = query.where((eb) => eb.or([eb("updated_at", "is", null), eb("updated_at", "<", ts)]));
899
- runCompiled(this.db, query.compile());
939
+ query = query.where("deleted_at", "is", null);
940
+ if (conditions?.ifUpdatedAt !== void 0) {
941
+ query = query.where("updated_at", "=", conditions.ifUpdatedAt);
942
+ }
943
+ return countCompiled(this.db, query.returning(WRITTEN).compile());
900
944
  }
901
945
  /**
902
946
  * Whether this table exists in *this* database.