@enbox/dwn-sql-store 0.0.9 → 0.0.11

package/src/migrations/001-initial-schema.ts

@@ -1,6 +1,6 @@
 import type { Dialect } from '../dialect/dialect.js';
-import type { Kysely } from 'kysely';
-import type { Migration } from '../migration-runner.js';
+import type { DwnMigrationFactory } from '../migration-provider.js';
+import type { Kysely, Migration } from 'kysely';
 
 import { sql } from 'kysely';
 
@@ -8,13 +8,12 @@ import { sql } from 'kysely';
  * Baseline migration: captures the schema as of the pre-migration era.
  *
  * For existing databases that already have these tables, this migration is
- * detected as "already applied" during the adoption bootstrap (see MigrationRunner).
+ * detected as "already applied" during the adoption bootstrap (see runDwnStoreMigrations).
  * For new databases, this creates the full initial schema.
  */
-export const migration001InitialSchema: Migration = {
-  name: '001-initial-schema',
+export const migration001InitialSchema: DwnMigrationFactory = (dialect: Dialect): Migration => ({
 
-  async up(db: Kysely<any>, dialect: Dialect): Promise<void> {
+  async up(db: Kysely<any>): Promise<void> {
 
     // ─── messageStoreMessages ───────────────────────────────────────────
     if (!(await dialect.hasTable(db, 'messageStoreMessages'))) {
@@ -187,4 +186,4 @@ export const migration001InitialSchema: Migration = {
         .on('stateIndexMeta').columns(['tenant', 'messageCid']).execute();
     }
   },
-};
+});

package/src/migrations/002-content-addressed-datastore.ts

@@ -1,6 +1,6 @@
 import type { Dialect } from '../dialect/dialect.js';
-import type { Kysely } from 'kysely';
-import type { Migration } from '../migration-runner.js';
+import type { DwnMigrationFactory } from '../migration-provider.js';
+import type { Kysely, Migration } from 'kysely';
 
 import { sql } from 'kysely';
 
@@ -29,10 +29,9 @@ import { sql } from 'kysely';
  * NOTE: For large databases, the data migration may take significant time.
  * The migration runs in a single transaction for atomicity.
  */
-export const migration002ContentAddressedDatastore: Migration = {
-  name: '002-content-addressed-datastore',
+export const migration002ContentAddressedDatastore: DwnMigrationFactory = (dialect: Dialect): Migration => ({
 
-  async up(db: Kysely<any>, dialect: Dialect): Promise<void> {
+  async up(db: Kysely<any>): Promise<void> {
 
     // ─── Create dataRefs table ──────────────────────────────────────────
     if (!(await dialect.hasTable(db, 'dataRefs'))) {
@@ -137,4 +136,4 @@ export const migration002ContentAddressedDatastore: Migration = {
       await db.schema.dropTable('dataStore').execute();
     }
   },
-};
+});

package/src/migrations/003-add-squash-column.ts

@@ -1,6 +1,5 @@
-import type { Dialect } from '../dialect/dialect.js';
-import type { Kysely } from 'kysely';
-import type { Migration } from '../migration-runner.js';
+import type { DwnMigrationFactory } from '../migration-provider.js';
+import type { Kysely, Migration } from 'kysely';
 
 /**
  * Migration 003: Add `squash` boolean column to `messageStoreMessages`.
@@ -9,13 +8,12 @@ import type { Migration } from '../migration-runner.js';
  * introduced in the DWN spec. It follows the same pattern as `published`
  * and `prune` — a nullable boolean column used for query filtering.
  */
-export const migration003AddSquashColumn: Migration = {
-  name: '003-add-squash-column',
+export const migration003AddSquashColumn: DwnMigrationFactory = (): Migration => ({
 
-  async up(db: Kysely<any>, _dialect: Dialect): Promise<void> {
+  async up(db: Kysely<any>): Promise<void> {
     await db.schema
       .alterTable('messageStoreMessages')
       .addColumn('squash', 'boolean')
       .execute();
   },
-};
+});

package/src/migrations/index.ts

@@ -1,15 +1,23 @@
-import type { Migration } from '../migration-runner.js';
+import type { DwnMigrationFactory } from '../migration-provider.js';
 
 import { migration001InitialSchema } from './001-initial-schema.js';
 import { migration002ContentAddressedDatastore } from './002-content-addressed-datastore.js';
 import { migration003AddSquashColumn } from './003-add-squash-column.js';
 
 /**
- * All migrations in sequential order. The MigrationRunner applies them
- * in array order, skipping any that have already been recorded.
+ * All DWN store migrations in sequential order.
+ *
+ * Each entry is a `[name, factory]` tuple where the factory is a
+ * {@link DwnMigrationFactory} that receives the dialect and returns a
+ * standard Kysely `Migration`. The `DwnMigrationProvider` resolves these
+ * into the `Record<string, Migration>` that Kysely's `Migrator` expects.
+ *
+ * **Ordering contract:** Entries MUST be sorted by name (lexicographic).
+ * Kysely's `Migrator` sorts by key as well, but maintaining order here
+ * makes the source of truth explicit and human-readable.
  */
-export const allMigrations: Migration[] = [
-  migration001InitialSchema,
-  migration002ContentAddressedDatastore,
-  migration003AddSquashColumn,
+export const allDwnMigrations: ReadonlyArray<readonly [name: string, factory: DwnMigrationFactory]> = [
+  ['001-initial-schema', migration001InitialSchema],
+  ['002-content-addressed-datastore', migration002ContentAddressedDatastore],
+  ['003-add-squash-column', migration003AddSquashColumn],
 ];

package/src/resumable-task-store-sql.ts

@@ -4,7 +4,7 @@ import type { ManagedResumableTask, ResumableTaskStore } from '@enbox/dwn-sdk-js
 
 import { Cid } from '@enbox/dwn-sdk-js';
 import { executeWithTransaction } from './utils/transaction.js';
-import { Kysely } from 'kysely';
+import { Kysely, sql } from 'kysely';
 
 export class ResumableTaskStoreSql implements ResumableTaskStore {
   private static readonly taskTimeoutInSeconds = 60;
@@ -23,31 +23,22 @@ export class ResumableTaskStoreSql implements ResumableTaskStore {
 
     this.#db = new Kysely<DwnDatabaseType>({ dialect: this.#dialect });
 
-    // if table already exists, there is no more things todo
-    const tableName = 'resumableTasks';
-    const tableExists = await this.#dialect.hasTable(this.#db, tableName);
-    if (tableExists) {
-      return;
-    }
-
-    // else create the table and corresponding indexes
-
-    const table = this.#db.schema
-      .createTable(tableName)
-      .ifNotExists() // kept to show supported by all dialects in contrast to ifNotExists() below, though not needed due to hasTable() check above
-      .addColumn('id', 'varchar(255)', (col) => col.primaryKey())
-      .addColumn('task', 'text')
-      .addColumn('timeout', 'bigint')
-      .addColumn('retryCount', 'integer');
-
-    await table.execute();
+    // Fail fast if migrations have not been run — tables must already exist.
+    await this.#assertTablesExist();
+  }
 
-    await this.#db.schema
-      .createIndex('index_timeout')
-      // .ifNotExists() // intentionally kept commented out code to show that it is not supported by all dialects (ie. MySQL)
-      .on('resumableTasks')
-      .column('timeout')
-      .execute();
+  /**
+   * Verifies that the required tables exist by executing a zero-row SELECT.
+   * Throws a clear error directing the caller to run migrations first.
+   */
+  async #assertTablesExist(): Promise<void> {
+    try {
+      await sql`SELECT 1 FROM ${sql.table('resumableTasks')} LIMIT 0`.execute(this.#db!);
+    } catch {
+      throw new Error(
+        'ResumableTaskStoreSql: table \'resumableTasks\' does not exist. Run DWN store migrations before opening stores.'
+      );
+    }
   }
 
   async close(): Promise<void> {

package/src/state-index-sql.ts

@@ -16,9 +16,9 @@ import type { KeyValues } from '@enbox/dwn-sdk-js';
 import type { StateIndex } from '@enbox/dwn-sdk-js';
 
 import { initDefaultHashes } from '@enbox/dwn-sdk-js';
-import { Kysely } from 'kysely';
 import { SMTStoreSql } from './smt-store-sql.js';
 import { SparseMerkleTree } from '@enbox/dwn-sdk-js';
+import { Kysely, sql } from 'kysely';
 
 export class StateIndexSql implements StateIndex {
   #dialect: Dialect;
@@ -51,68 +51,24 @@ export class StateIndexSql implements StateIndex {
     // Ensure default hashes are initialized for the SMT
     await initDefaultHashes();
 
-    // ─── Create stateIndexNodes table ─────────────────────────────────────
-    const nodesTableName = 'stateIndexNodes';
-    const nodesTableExists = await this.#dialect.hasTable(this.#db, nodesTableName);
-    if (!nodesTableExists) {
-      await this.#db.schema
-        .createTable(nodesTableName)
-        .ifNotExists()
-        .addColumn('tenant', 'varchar(255)', (col) => col.notNull())
-        .addColumn('scope', 'varchar(200)', (col) => col.notNull())
-        .addColumn('nodeHash', 'varchar(64)', (col) => col.notNull())
-        .addColumn('nodeType', 'varchar(10)', (col) => col.notNull())
-        .addColumn('leftHash', 'varchar(64)')
-        .addColumn('rightHash', 'varchar(64)')
-        .addColumn('leafKeyHash', 'varchar(64)')
-        .addColumn('leafValueCid', 'varchar(60)')
-        .execute();
-
-      // Not UNIQUE because the delete-then-insert upsert pattern in SMTStoreSql
-      // can race under concurrent access, causing duplicate key violations.
-      await this.#db.schema
-        .createIndex('index_stateIndexNodes_tenant_scope_nodeHash')
-        .on(nodesTableName)
-        .columns(['tenant', 'scope', 'nodeHash'])
-        .execute();
-    }
-
-    // ─── Create stateIndexRoots table ─────────────────────────────────────
-    const rootsTableName = 'stateIndexRoots';
-    const rootsTableExists = await this.#dialect.hasTable(this.#db, rootsTableName);
-    if (!rootsTableExists) {
-      await this.#db.schema
-        .createTable(rootsTableName)
-        .ifNotExists()
-        .addColumn('tenant', 'varchar(255)', (col) => col.notNull())
-        .addColumn('scope', 'varchar(200)', (col) => col.notNull())
-        .addColumn('rootHash', 'varchar(64)', (col) => col.notNull())
-        .execute();
-
-      await this.#db.schema
-        .createIndex('index_stateIndexRoots_tenant_scope')
-        .on(rootsTableName)
-        .columns(['tenant', 'scope'])
-        .execute();
-    }
-
-    // ─── Create stateIndexMeta table ──────────────────────────────────────
-    const metaTableName = 'stateIndexMeta';
-    const metaTableExists = await this.#dialect.hasTable(this.#db, metaTableName);
-    if (!metaTableExists) {
-      await this.#db.schema
-        .createTable(metaTableName)
-        .ifNotExists()
-        .addColumn('tenant', 'varchar(255)', (col) => col.notNull())
-        .addColumn('messageCid', 'varchar(60)', (col) => col.notNull())
-        .addColumn('protocol', 'varchar(200)')
-        .execute();
+    // Fail fast if migrations have not been run — tables must already exist.
+    await this.#assertTablesExist();
+  }
 
-      await this.#db.schema
-        .createIndex('index_stateIndexMeta_tenant_messageCid')
-        .on(metaTableName)
-        .columns(['tenant', 'messageCid'])
-        .execute();
+  /**
+   * Verifies that the required tables exist by executing a zero-row SELECT.
+   * Throws a clear error directing the caller to run migrations first.
+   */
+  async #assertTablesExist(): Promise<void> {
+    const tables = ['stateIndexNodes', 'stateIndexRoots', 'stateIndexMeta'] as const;
+    for (const table of tables) {
+      try {
+        await sql`SELECT 1 FROM ${sql.table(table)} LIMIT 0`.execute(this.#db!);
+      } catch {
+        throw new Error(
+          `StateIndexSql: table '${table}' does not exist. Run DWN store migrations before opening stores.`
+        );
+      }
     }
   }
 

package/src/utils/filter.ts

@@ -2,7 +2,7 @@ import type { DwnDatabaseType } from '../types.js';
 import type { Filter } from '@enbox/dwn-sdk-js';
 import type { ExpressionBuilder, OperandExpression, SelectQueryBuilder, SqlBool } from 'kysely';
 
-import { DynamicModule } from 'kysely';
+import { DynamicModule, sql } from 'kysely';
 import { sanitizedValue, sanitizeFiltersAndSeparateTags } from './sanitize.js';
 
 /**
@@ -52,6 +52,16 @@ function processFilter<DB = DwnDatabaseType, TB extends keyof DB = keyof DB>(
     if (Array.isArray(value)) { // OneOfFilter
       andOperands.push(eb(column, 'in', value));
     } else if (typeof value === 'object') { // RangeFilter
+      // Detect prefix-style range filters created by `constructPrefixFilterAsRangeFilter`
+      // which uses `{ gte: prefix, lt: prefix + '\uffff' }`. The U+FFFF sentinel does not
+      // sort correctly under ICU/libc collation rules (e.g. PostgreSQL's en_US.UTF-8),
+      // so we convert these to a collation-safe SQL LIKE expression.
+      if (isPrefixRangeFilter(value)) {
+        const prefix = escapeLikePattern(value.gte as string);
+        andOperands.push(sql`${sql.ref(property)} LIKE ${prefix + '%'}`);
+        continue;
+      }
+
       if (value.gt) {
         andOperands.push(eb(column, '>', sanitizedValue(value.gt)));
       }
@@ -70,6 +80,30 @@ function processFilter<DB = DwnDatabaseType, TB extends keyof DB = keyof DB>(
   }
 }
 
+/**
+ * Returns `true` if the given RangeFilter matches the pattern produced by
+ * `constructPrefixFilterAsRangeFilter`: `{ gte: <prefix>, lt: <prefix> + '\uffff' }`.
+ */
+function isPrefixRangeFilter(value: Record<string, unknown>): boolean {
+  if (typeof value.gte !== 'string' || typeof value.lt !== 'string') {
+    return false;
+  }
+  // Only two keys: gte and lt (no gt, lte, or other properties)
+  const keys = Object.keys(value);
+  if (keys.length !== 2 || !keys.includes('gte') || !keys.includes('lt')) {
+    return false;
+  }
+  return value.lt === value.gte + '\uffff';
+}
+
+/**
+ * Escapes SQL LIKE meta-characters (`%`, `_`) in the given string so that
+ * they are matched literally.
+ */
+function escapeLikePattern(input: string): string {
+  return input.replace(/%/g, '\\%').replace(/_/g, '\\_');
+}
+
 /**
  * Processes each property in the tags filter as an AND operand and adds it to the `andOperands` array.
  * If a property has an array of values it will treat it as a OneOf (IN) within the overall AND query.