@starkeep/storage-sqlite 0.5.3 → 0.6.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/dist/index.d.cts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { S as SqliteDatabaseAdapter, a as SqliteDatabaseAdapterOptions, b as SqliteDriver } from './adapter-DoVOV6K-.cjs';
2
2
  import { Kysely } from 'kysely';
3
3
  import { RawDatabase, DigestBucket, ParsedQuery, BuildOptions, ParsedQueryResult } from '@starkeep/storage-adapter';
4
- import { AppSyncableNamespaceStore, AppSyncableNamespace, AppSyncableTableInfo, AppSyncableApplier, ScanCapableApplier, AppSyncableRowEntry, ScanSincePage } from '@starkeep/shared-space-api';
4
+ import { AppSyncableNamespaceStore, AppSyncableNamespace, AppSyncableTableInfo, AppSyncableApplier, ScanCapableApplier, AppSyncableRowEntry, ScanSincePage, DeclaredColumn } from '@starkeep/shared-space-api';
5
5
  export { AppSyncableNamespace, AppSyncableTableInfo } from '@starkeep/shared-space-api';
6
6
  import { HLCTimestamp } from '@starkeep/protocol-primitives';
7
7
 
@@ -143,6 +143,51 @@ declare class SqliteAppSyncableApplier implements AppSyncableApplier, ScanCapabl
143
143
  private selectRows;
144
144
  }
145
145
 
146
+ /**
147
+ * One syncable table as an app's manifest declares it: the structural shape of
148
+ * admin-manifest's `SyncableTable`, so this package needs no manifest schema
149
+ * and a phone can pass the block straight from the manifest JSON.
150
+ */
151
+ interface SyncableTableDeclaration {
152
+ readonly name: string;
153
+ readonly columns: readonly DeclaredColumn[];
154
+ readonly indexes?: readonly {
155
+ readonly columns: readonly string[];
156
+ }[];
157
+ }
158
+ /** A manifest's `infraRequirements.appSpecificSyncable` block. */
159
+ interface AppSyncableDeclaration {
160
+ readonly tables: readonly SyncableTableDeclaration[];
161
+ readonly files?: boolean;
162
+ }
163
+ declare function createAppSyncableTables(db: RawDatabase, appId: string, tables: readonly SyncableTableDeclaration[]): void;
164
+ /**
165
+ * Create the framework-owned `_starkeep_sync_records` table for an app that
166
+ * opted into `filesEnabled`. Same column shape as the manifest-declared
167
+ * syncable tables (plus the standard updated_at/deleted_at HLC columns) so
168
+ * the LWW applier can treat it uniformly.
169
+ */
170
+ declare function createReservedFileRecordsTable(db: RawDatabase, appId: string): void;
171
+ /**
172
+ * The namespace registry's description of an app's tables: the declared ones,
173
+ * plus the reserved file-records table when files are enabled. Derived from
174
+ * the declaration rather than read back from SQLite, because a declared type
175
+ * is not recoverable from a physical column, and it runs in the data server,
176
+ * which never sees a manifest.
177
+ */
178
+ declare function appSyncableNamespaceTables(syncable: AppSyncableDeclaration): AppSyncableTableInfo[];
179
+ /**
180
+ * Create an app's syncable tables and register its namespace, from its
181
+ * manifest's `appSpecificSyncable` block. Idempotent, so a node may run it on
182
+ * every start.
183
+ *
184
+ * The desktop's local installer runs the same two halves as separate ledger
185
+ * steps; a node that holds an app's private data without installing the app,
186
+ * as Photos Mobile does, calls this once at bring-up. Both therefore create
187
+ * identical tables.
188
+ */
189
+ declare function registerAppSyncableNamespace(db: RawDatabase, appId: string, syncable: AppSyncableDeclaration): void;
190
+
146
191
  /**
147
192
  * Which user a node's library belongs to, and the database half of binding it.
148
193
  *
@@ -211,4 +256,4 @@ declare function checkLibraryBindable(db: RawDatabase, userId: string): void;
211
256
  */
212
257
  declare function commitLibraryBinding(db: RawDatabase, userId: string, extraKeyColumns?: readonly LibraryKeyColumn[]): number;
213
258
 
214
- export { LibraryBoundElsewhereError, type LibraryKeyColumn, SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore, appSyncableTableName, applyConnectionPragmas, boundUserId, checkLibraryBindable, commitLibraryBinding, deleteAppSyncableNamespace, getAppSyncableNamespace, initializeLocalSchema, libraryKeyColumns, libraryUserSegment, listAppSyncableNamespaces, compiler as sqliteCompiler, upsertAppSyncableNamespace };
259
+ export { type AppSyncableDeclaration, LibraryBoundElsewhereError, type LibraryKeyColumn, SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore, type SyncableTableDeclaration, appSyncableNamespaceTables, appSyncableTableName, applyConnectionPragmas, boundUserId, checkLibraryBindable, commitLibraryBinding, createAppSyncableTables, createReservedFileRecordsTable, deleteAppSyncableNamespace, getAppSyncableNamespace, initializeLocalSchema, libraryKeyColumns, libraryUserSegment, listAppSyncableNamespaces, registerAppSyncableNamespace, compiler as sqliteCompiler, upsertAppSyncableNamespace };
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { S as SqliteDatabaseAdapter, a as SqliteDatabaseAdapterOptions, b as SqliteDriver } from './adapter-DoVOV6K-.js';
2
2
  import { Kysely } from 'kysely';
3
3
  import { RawDatabase, DigestBucket, ParsedQuery, BuildOptions, ParsedQueryResult } from '@starkeep/storage-adapter';
4
- import { AppSyncableNamespaceStore, AppSyncableNamespace, AppSyncableTableInfo, AppSyncableApplier, ScanCapableApplier, AppSyncableRowEntry, ScanSincePage } from '@starkeep/shared-space-api';
4
+ import { AppSyncableNamespaceStore, AppSyncableNamespace, AppSyncableTableInfo, AppSyncableApplier, ScanCapableApplier, AppSyncableRowEntry, ScanSincePage, DeclaredColumn } from '@starkeep/shared-space-api';
5
5
  export { AppSyncableNamespace, AppSyncableTableInfo } from '@starkeep/shared-space-api';
6
6
  import { HLCTimestamp } from '@starkeep/protocol-primitives';
7
7
 
@@ -143,6 +143,51 @@ declare class SqliteAppSyncableApplier implements AppSyncableApplier, ScanCapabl
143
143
  private selectRows;
144
144
  }
145
145
 
146
+ /**
147
+ * One syncable table as an app's manifest declares it: the structural shape of
148
+ * admin-manifest's `SyncableTable`, so this package needs no manifest schema
149
+ * and a phone can pass the block straight from the manifest JSON.
150
+ */
151
+ interface SyncableTableDeclaration {
152
+ readonly name: string;
153
+ readonly columns: readonly DeclaredColumn[];
154
+ readonly indexes?: readonly {
155
+ readonly columns: readonly string[];
156
+ }[];
157
+ }
158
+ /** A manifest's `infraRequirements.appSpecificSyncable` block. */
159
+ interface AppSyncableDeclaration {
160
+ readonly tables: readonly SyncableTableDeclaration[];
161
+ readonly files?: boolean;
162
+ }
163
+ declare function createAppSyncableTables(db: RawDatabase, appId: string, tables: readonly SyncableTableDeclaration[]): void;
164
+ /**
165
+ * Create the framework-owned `_starkeep_sync_records` table for an app that
166
+ * opted into `filesEnabled`. Same column shape as the manifest-declared
167
+ * syncable tables (plus the standard updated_at/deleted_at HLC columns) so
168
+ * the LWW applier can treat it uniformly.
169
+ */
170
+ declare function createReservedFileRecordsTable(db: RawDatabase, appId: string): void;
171
+ /**
172
+ * The namespace registry's description of an app's tables: the declared ones,
173
+ * plus the reserved file-records table when files are enabled. Derived from
174
+ * the declaration rather than read back from SQLite, because a declared type
175
+ * is not recoverable from a physical column, and it runs in the data server,
176
+ * which never sees a manifest.
177
+ */
178
+ declare function appSyncableNamespaceTables(syncable: AppSyncableDeclaration): AppSyncableTableInfo[];
179
+ /**
180
+ * Create an app's syncable tables and register its namespace, from its
181
+ * manifest's `appSpecificSyncable` block. Idempotent, so a node may run it on
182
+ * every start.
183
+ *
184
+ * The desktop's local installer runs the same two halves as separate ledger
185
+ * steps; a node that holds an app's private data without installing the app,
186
+ * as Photos Mobile does, calls this once at bring-up. Both therefore create
187
+ * identical tables.
188
+ */
189
+ declare function registerAppSyncableNamespace(db: RawDatabase, appId: string, syncable: AppSyncableDeclaration): void;
190
+
146
191
  /**
147
192
  * Which user a node's library belongs to, and the database half of binding it.
148
193
  *
@@ -211,4 +256,4 @@ declare function checkLibraryBindable(db: RawDatabase, userId: string): void;
211
256
  */
212
257
  declare function commitLibraryBinding(db: RawDatabase, userId: string, extraKeyColumns?: readonly LibraryKeyColumn[]): number;
213
258
 
214
- export { LibraryBoundElsewhereError, type LibraryKeyColumn, SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore, appSyncableTableName, applyConnectionPragmas, boundUserId, checkLibraryBindable, commitLibraryBinding, deleteAppSyncableNamespace, getAppSyncableNamespace, initializeLocalSchema, libraryKeyColumns, libraryUserSegment, listAppSyncableNamespaces, compiler as sqliteCompiler, upsertAppSyncableNamespace };
259
+ export { type AppSyncableDeclaration, LibraryBoundElsewhereError, type LibraryKeyColumn, SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore, type SyncableTableDeclaration, appSyncableNamespaceTables, appSyncableTableName, applyConnectionPragmas, boundUserId, checkLibraryBindable, commitLibraryBinding, createAppSyncableTables, createReservedFileRecordsTable, deleteAppSyncableNamespace, getAppSyncableNamespace, initializeLocalSchema, libraryKeyColumns, libraryUserSegment, listAppSyncableNamespaces, registerAppSyncableNamespace, compiler as sqliteCompiler, upsertAppSyncableNamespace };
package/dist/index.js CHANGED
@@ -357,14 +357,14 @@ var SqliteDatabaseAdapter = class {
357
357
  // JavaScript boolean and threw "Provided value cannot be bound to SQLite
358
358
  // parameter". Nothing had exercised it because no metadata column was a
359
359
  // boolean until `exif_present`.
360
- runStmt(sql4, ...params) {
361
- this.getDatabase().prepare(sql4).run(...params.map(toSqliteParam));
360
+ runStmt(sql5, ...params) {
361
+ this.getDatabase().prepare(sql5).run(...params.map(toSqliteParam));
362
362
  }
363
- getRow(sql4, ...params) {
364
- return this.getDatabase().prepare(sql4).get(...params.map(toSqliteParam));
363
+ getRow(sql5, ...params) {
364
+ return this.getDatabase().prepare(sql5).get(...params.map(toSqliteParam));
365
365
  }
366
- allRows(sql4, ...params) {
367
- return this.getDatabase().prepare(sql4).all(...params.map(toSqliteParam));
366
+ allRows(sql5, ...params) {
367
+ return this.getDatabase().prepare(sql5).all(...params.map(toSqliteParam));
368
368
  }
369
369
  async put(record) {
370
370
  const row = recordToRow(record);
@@ -436,8 +436,8 @@ var SqliteDatabaseAdapter = class {
436
436
  return mergeDigestBuckets(out);
437
437
  }
438
438
  async query(query) {
439
- const { sql: sql4, params } = buildSelectQuery(query);
440
- const rows = this.allRows(sql4, ...params);
439
+ const { sql: sql5, params } = buildSelectQuery(query);
440
+ const rows = this.allRows(sql5, ...params);
441
441
  const limit = query.limit;
442
442
  const hasMore = limit ? rows.length > limit : false;
443
443
  const resultRows = hasMore ? rows.slice(0, limit) : rows;
@@ -451,13 +451,13 @@ var SqliteDatabaseAdapter = class {
451
451
  };
452
452
  }
453
453
  async countRecords(query) {
454
- const { sql: sql4, params } = buildCountQuery(query);
455
- const row = this.getRow(sql4, ...params);
454
+ const { sql: sql5, params } = buildCountQuery(query);
455
+ const row = this.getRow(sql5, ...params);
456
456
  return row?.total ?? 0;
457
457
  }
458
458
  async countRecordsByType(query) {
459
- const { sql: sql4, params } = buildTypeCountsQuery(query);
460
- const rows = this.allRows(sql4, ...params);
459
+ const { sql: sql5, params } = buildTypeCountsQuery(query);
460
+ const rows = this.allRows(sql5, ...params);
461
461
  return rows.map((row) => ({
462
462
  type: row.type,
463
463
  count: Number(row.count),
@@ -1065,8 +1065,90 @@ function nodeIdOf(updatedAt, entry) {
1065
1065
  return entry.timestamp.nodeId;
1066
1066
  }
1067
1067
 
1068
- // src/library-owner.ts
1068
+ // src/app-syncable/tables.ts
1069
1069
  import { sql as sql3 } from "kysely";
1070
+ import {
1071
+ FILE_RECORDS_COLUMNS,
1072
+ FILE_RECORDS_TABLE,
1073
+ FILE_RECORDS_TABLE_INFO,
1074
+ appSyncableTableInfo,
1075
+ syncableIndexName
1076
+ } from "@starkeep/shared-space-api";
1077
+ import { sqliteColumnType } from "@starkeep/protocol-primitives";
1078
+ function createSyncableTable(db, fullName, columns, indexes = []) {
1079
+ let tb = compiler.schema.createTable(fullName).ifNotExists();
1080
+ for (const c of columns) {
1081
+ tb = tb.addColumn(c.name, sql3.raw(c.type), (col) => {
1082
+ const withNull = c.notNull || c.primaryKey ? col.notNull() : col;
1083
+ return c.boolean ? withNull.check(sql3`${sql3.ref(c.name)} in (0, 1)`) : withNull;
1084
+ });
1085
+ }
1086
+ tb = tb.addColumn("updated_at", "text", (col) => col.notNull()).addColumn("node_id", "text", (col) => col.notNull()).addColumn("deleted_at", "text");
1087
+ const pks = columns.filter((c) => c.primaryKey).map((c) => c.name);
1088
+ if (pks.length > 0) {
1089
+ tb = tb.addPrimaryKeyConstraint(`pk_${fullName}`, pks);
1090
+ }
1091
+ db.exec(tb.compile().sql);
1092
+ db.exec(
1093
+ compiler.schema.createIndex(`idx_${fullName}_updated_at`).ifNotExists().on(fullName).column("updated_at").compile().sql
1094
+ );
1095
+ db.exec(
1096
+ compiler.schema.createIndex(`idx_${fullName}_node_watermark`).ifNotExists().on(fullName).columns(["node_id", "updated_at"]).compile().sql
1097
+ );
1098
+ for (const index of indexes) {
1099
+ db.exec(
1100
+ compiler.schema.createIndex(syncableIndexName(fullName, [...index.columns])).ifNotExists().on(fullName).columns([...index.columns]).compile().sql
1101
+ );
1102
+ }
1103
+ }
1104
+ function createAppSyncableTables(db, appId, tables) {
1105
+ for (const table of tables) {
1106
+ createSyncableTable(
1107
+ db,
1108
+ appSyncableTableName(appId, table.name),
1109
+ table.columns.map((c) => ({
1110
+ name: c.name,
1111
+ type: sqliteColumnType(c.type),
1112
+ notNull: Boolean(c.notNull),
1113
+ primaryKey: Boolean(c.primaryKey),
1114
+ boolean: c.type === "boolean"
1115
+ })),
1116
+ table.indexes
1117
+ );
1118
+ }
1119
+ }
1120
+ function createReservedFileRecordsTable(db, appId) {
1121
+ createSyncableTable(
1122
+ db,
1123
+ appSyncableTableName(appId, FILE_RECORDS_TABLE),
1124
+ // Through the one mapping, like `createAppSyncableTables` above. This was a
1125
+ // hand-written ternary whose Postgres twin in `dsql-ddl.ts` answered
1126
+ // `bigint` where this one answered `integer`, for one declared type.
1127
+ FILE_RECORDS_COLUMNS.map((c) => ({
1128
+ name: c.name,
1129
+ type: sqliteColumnType(c.type),
1130
+ notNull: Boolean(c.notNull),
1131
+ primaryKey: Boolean(c.primaryKey)
1132
+ }))
1133
+ );
1134
+ }
1135
+ function appSyncableNamespaceTables(syncable) {
1136
+ const declared = syncable.tables.map((t) => appSyncableTableInfo(t.name, t.columns));
1137
+ return syncable.files ? [...declared, FILE_RECORDS_TABLE_INFO] : declared;
1138
+ }
1139
+ function registerAppSyncableNamespace(db, appId, syncable) {
1140
+ createAppSyncableTables(db, appId, syncable.tables);
1141
+ if (syncable.files) createReservedFileRecordsTable(db, appId);
1142
+ upsertAppSyncableNamespace(
1143
+ db,
1144
+ appId,
1145
+ appSyncableNamespaceTables(syncable),
1146
+ syncable.files === true
1147
+ );
1148
+ }
1149
+
1150
+ // src/library-owner.ts
1151
+ import { sql as sql4 } from "kysely";
1070
1152
  import { LOCAL_USER_SEGMENT, USER_SEGMENT_PATTERN } from "@starkeep/protocol-primitives";
1071
1153
  var OWNER_TABLE = "library_owner";
1072
1154
  function ensureOwnerTable(db) {
@@ -1077,7 +1159,7 @@ function ensureOwnerTable(db) {
1077
1159
  function boundUserId(db) {
1078
1160
  ensureOwnerTable(db);
1079
1161
  const row = db.prepare(
1080
- compiler.selectFrom(OWNER_TABLE).select("user_id").where("id", "=", sql3.lit(0)).compile().sql
1162
+ compiler.selectFrom(OWNER_TABLE).select("user_id").where("id", "=", sql4.lit(0)).compile().sql
1081
1163
  ).get();
1082
1164
  return row?.user_id ?? null;
1083
1165
  }
@@ -1095,7 +1177,7 @@ function coreKeyColumns(db) {
1095
1177
  { table: "resident_keys", column: "record_id", primaryKey: false }
1096
1178
  ];
1097
1179
  const tables = db.prepare(
1098
- compiler.selectFrom("sqlite_master").select("name").where("type", "=", sql3.lit("table")).compile().sql
1180
+ compiler.selectFrom("sqlite_master").select("name").where("type", "=", sql4.lit("table")).compile().sql
1099
1181
  ).all();
1100
1182
  for (const { name } of tables) {
1101
1183
  if (name.endsWith("__starkeep_sync_records")) {
@@ -1109,20 +1191,20 @@ function coreKeyColumns(db) {
1109
1191
  }
1110
1192
  function tableExists(db, table) {
1111
1193
  return db.prepare(
1112
- compiler.selectFrom("sqlite_master").select("name").where("type", "=", sql3.lit("table")).where("name", "=", sql3.lit(table)).compile().sql
1194
+ compiler.selectFrom("sqlite_master").select("name").where("type", "=", sql4.lit("table")).where("name", "=", sql4.lit(table)).compile().sql
1113
1195
  ).get() !== void 0;
1114
1196
  }
1115
1197
  function namespaces(column, userId) {
1116
1198
  return [
1117
1199
  {
1118
- local: sql3.lit(`shared/${LOCAL_USER_SEGMENT}/%`),
1200
+ local: sql4.lit(`shared/${LOCAL_USER_SEGMENT}/%`),
1119
1201
  // Keeps the slash after `local`, so `shared/local/x` becomes `shared/<userId>/x`.
1120
- rebound: sql3`'shared/' || ${sql3.lit(userId)} || substr(${sql3.ref(column)}, ${sql3.lit(`shared/${LOCAL_USER_SEGMENT}`.length + 1)})`
1202
+ rebound: sql4`'shared/' || ${sql4.lit(userId)} || substr(${sql4.ref(column)}, ${sql4.lit(`shared/${LOCAL_USER_SEGMENT}`.length + 1)})`
1121
1203
  },
1122
1204
  // apps/<appId>/local/syncable/... — the app id is the segment before `local`.
1123
1205
  {
1124
- local: sql3.lit(`apps/%/${LOCAL_USER_SEGMENT}/syncable/%`),
1125
- rebound: sql3`replace(${sql3.ref(column)}, ${sql3.lit(`/${LOCAL_USER_SEGMENT}/syncable/`)}, ${sql3.lit(`/${userId}/syncable/`)})`
1206
+ local: sql4.lit(`apps/%/${LOCAL_USER_SEGMENT}/syncable/%`),
1207
+ rebound: sql4`replace(${sql4.ref(column)}, ${sql4.lit(`/${LOCAL_USER_SEGMENT}/syncable/`)}, ${sql4.lit(`/${userId}/syncable/`)})`
1126
1208
  }
1127
1209
  ];
1128
1210
  }
@@ -1130,12 +1212,12 @@ function rebindColumn(db, { table, column, primaryKey }, userId) {
1130
1212
  let changed = 0;
1131
1213
  for (const { local, rebound } of namespaces(column, userId)) {
1132
1214
  if (primaryKey) {
1133
- const duplicates = compiler.deleteFrom(table).where(sql3.ref(column), "like", local).where(
1134
- sql3`${rebound} in (${compiler.selectFrom(table).select(sql3.ref(column).as("k"))})`
1215
+ const duplicates = compiler.deleteFrom(table).where(sql4.ref(column), "like", local).where(
1216
+ sql4`${rebound} in (${compiler.selectFrom(table).select(sql4.ref(column).as("k"))})`
1135
1217
  ).compile();
1136
1218
  db.prepare(duplicates.sql).run(...duplicates.parameters);
1137
1219
  }
1138
- const update = compiler.updateTable(table).set({ [column]: rebound }).where(sql3.ref(column), "like", local).compile();
1220
+ const update = compiler.updateTable(table).set({ [column]: rebound }).where(sql4.ref(column), "like", local).compile();
1139
1221
  const result = db.prepare(update.sql).run(...update.parameters);
1140
1222
  changed += Number(result.changes ?? 0);
1141
1223
  }
@@ -1170,7 +1252,7 @@ function commitLibraryBinding(db, userId, extraKeyColumns = []) {
1170
1252
  try {
1171
1253
  for (const column of columns) rewritten += rebindColumn(db, column, userId);
1172
1254
  db.prepare(
1173
- compiler.insertInto(OWNER_TABLE).values({ id: sql3.lit(0), user_id: sql3.raw("?") }).onConflict(
1255
+ compiler.insertInto(OWNER_TABLE).values({ id: sql4.lit(0), user_id: sql4.raw("?") }).onConflict(
1174
1256
  (oc) => oc.column("id").doUpdateSet((eb) => ({ user_id: eb.ref("excluded.user_id") }))
1175
1257
  ).compile().sql
1176
1258
  ).run(userId);
@@ -1186,17 +1268,21 @@ export {
1186
1268
  SqliteAppSyncableApplier,
1187
1269
  SqliteAppSyncableNamespaceStore,
1188
1270
  SqliteDatabaseAdapter,
1271
+ appSyncableNamespaceTables,
1189
1272
  appSyncableTableName,
1190
1273
  applyConnectionPragmas,
1191
1274
  boundUserId,
1192
1275
  checkLibraryBindable,
1193
1276
  commitLibraryBinding,
1277
+ createAppSyncableTables,
1278
+ createReservedFileRecordsTable,
1194
1279
  deleteAppSyncableNamespace,
1195
1280
  getAppSyncableNamespace,
1196
1281
  initializeLocalSchema,
1197
1282
  libraryKeyColumns,
1198
1283
  libraryUserSegment,
1199
1284
  listAppSyncableNamespaces,
1285
+ registerAppSyncableNamespace,
1200
1286
  compiler as sqliteCompiler,
1201
1287
  upsertAppSyncableNamespace
1202
1288
  };