@holo-js/cache-db 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { CacheDriverContract } from '@holo-js/cache';
+import { HoloProjectConnectionConfig, DatabaseContext, DatabaseContextOptions, SupportedDatabaseDriver } from '@holo-js/db';
+
+declare const DEFAULT_CACHE_DATABASE_TABLE = "cache";
+declare const DEFAULT_CACHE_DATABASE_LOCK_TABLE = "cache_locks";
+type DatabaseCacheDriverOptions = {
+    readonly name: string;
+    readonly connectionName: string;
+    readonly table: string;
+    readonly lockTable: string;
+    readonly prefix?: string;
+    readonly connection: HoloProjectConnectionConfig | string;
+    readonly now?: () => number;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+    readonly ownerFactory?: () => string;
+};
+type DatabaseCacheEntryRow = {
+    readonly key: string;
+    readonly payload: string;
+    readonly expires_at: number | null;
+};
+type DatabaseCacheLockRow = {
+    readonly name: string;
+    readonly owner: string;
+    readonly expires_at: number;
+};
+type DatabaseReadResult<TValue> = {
+    readonly state: 'missing';
+} | {
+    readonly state: 'hit';
+    readonly value: TValue;
+};
+declare function defaultSleep(milliseconds: number): Promise<void>;
+declare function resolveDriver(connection: HoloProjectConnectionConfig | string): SupportedDatabaseDriver;
+declare function createDatabaseContextOptions(connectionName: string, connection: HoloProjectConnectionConfig | string): DatabaseContextOptions;
+declare function createDatabaseConnection(connectionName: string, connection: HoloProjectConnectionConfig | string): DatabaseContext;
+declare function prepareCacheDatabaseTables(connection: DatabaseContext, tableName?: string, lockTableName?: string): Promise<void>;
+declare function renderCacheTableMigration(tableName?: string, lockTableName?: string): string;
+declare function isDatabaseCacheTableMissingError(error: unknown, tableName: string, lockTableName: string): boolean;
+declare function normalizeDatabaseCacheTableError(error: unknown, tableName: string, lockTableName: string): never;
+declare function withDatabaseCacheTableGuard<TValue>(tableName: string, lockTableName: string, callback: () => Promise<TValue>): Promise<TValue>;
+declare function readEntry(connection: DatabaseContext, tableName: string, key: string, now: number): Promise<DatabaseReadResult<DatabaseCacheEntryRow>>;
+declare function readLock(connection: DatabaseContext, tableName: string, name: string, now: number): Promise<DatabaseReadResult<DatabaseCacheLockRow>>;
+declare function createDatabaseCacheDriver(options: DatabaseCacheDriverOptions): CacheDriverContract;
+declare const cacheDbInternals: {
+    createDatabaseConnection: typeof createDatabaseConnection;
+    createDatabaseContextOptions: typeof createDatabaseContextOptions;
+    defaultSleep: typeof defaultSleep;
+    isDatabaseCacheTableMissingError: typeof isDatabaseCacheTableMissingError;
+    normalizeDatabaseCacheTableError: typeof normalizeDatabaseCacheTableError;
+    prepareCacheDatabaseTables: typeof prepareCacheDatabaseTables;
+    readEntry: typeof readEntry;
+    readLock: typeof readLock;
+    renderCacheTableMigration: typeof renderCacheTableMigration;
+    resolveDriver: typeof resolveDriver;
+    withDatabaseCacheTableGuard: typeof withDatabaseCacheTableGuard;
+};
+
+export { DEFAULT_CACHE_DATABASE_LOCK_TABLE, DEFAULT_CACHE_DATABASE_TABLE, type DatabaseCacheDriverOptions, cacheDbInternals, createDatabaseCacheDriver };

package/dist/index.mjs

@@ -0,0 +1,378 @@
+// src/index.ts
+import { randomUUID } from "crypto";
+import {
+  CacheConfigError,
+  CacheInvalidNumericMutationError,
+  CacheLockAcquisitionError,
+  deserializeCacheValue,
+  serializeCacheValue
+} from "@holo-js/cache";
+import {
+  createConnectionManager,
+  createSchemaService,
+  createRuntimeConnectionOptions,
+  TableQueryBuilder
+} from "@holo-js/db";
+var DEFAULT_CACHE_DATABASE_TABLE = "cache";
+var DEFAULT_CACHE_DATABASE_LOCK_TABLE = "cache_locks";
+function defaultSleep(milliseconds) {
+  return new Promise((resolveDelay) => {
+    setTimeout(resolveDelay, milliseconds);
+  });
+}
+function resolveDriver(connection) {
+  if (typeof connection === "string") {
+    if (connection === ":memory:" || connection.startsWith("file:") || connection.startsWith("/") || connection.startsWith("./") || connection.startsWith("../") || connection.endsWith(".db") || connection.endsWith(".sqlite") || connection.endsWith(".sqlite3")) {
+      return "sqlite";
+    }
+    if (connection.startsWith("postgres://") || connection.startsWith("postgresql://")) {
+      return "postgres";
+    }
+    if (connection.startsWith("mysql://") || connection.startsWith("mysql2://")) {
+      return "mysql";
+    }
+    return "sqlite";
+  }
+  return connection.driver ?? (connection.url ? resolveDriver(connection.url) : "sqlite");
+}
+function createDatabaseContextOptions(connectionName, connection) {
+  const driver = resolveDriver(connection);
+  if (driver === "sqlite") {
+    const url = typeof connection === "string" ? connection : connection.url ?? connection.filename ?? ":memory:";
+    return createRuntimeConnectionOptions(driver, url, Boolean(typeof connection === "string" ? false : connection.logging), void 0, connectionName);
+  }
+  const parsedPort = typeof connection === "string" ? void 0 : typeof connection.port === "number" ? connection.port : typeof connection.port === "string" && /^\d+$/.test(connection.port.trim()) ? Number(connection.port.trim()) : void 0;
+  const port = typeof parsedPort === "number" && Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535 ? parsedPort : void 0;
+  return createRuntimeConnectionOptions(
+    driver,
+    typeof connection === "string" ? { url: connection } : {
+      url: connection.url,
+      host: connection.host,
+      port,
+      username: connection.username,
+      password: connection.password,
+      database: connection.database,
+      ssl: connection.ssl
+    },
+    Boolean(typeof connection === "string" ? false : connection.logging),
+    typeof connection === "string" ? void 0 : connection.schema,
+    connectionName
+  );
+}
+function createDatabaseConnection(connectionName, connection) {
+  return createConnectionManager({
+    defaultConnection: connectionName,
+    connections: {
+      [connectionName]: createDatabaseContextOptions(connectionName, connection)
+    }
+  }).connection(connectionName);
+}
+async function prepareCacheDatabaseTables(connection, tableName = DEFAULT_CACHE_DATABASE_TABLE, lockTableName = DEFAULT_CACHE_DATABASE_LOCK_TABLE) {
+  const schema = createSchemaService(connection);
+  await connection.initialize();
+  if (!await schema.hasTable(tableName)) {
+    await schema.createTable(tableName, (table) => {
+      table.string("key").primaryKey();
+      table.text("payload");
+      table.bigInteger("expires_at").nullable();
+      table.index(["expires_at"], `${tableName.replaceAll(".", "_")}_expires_at_index`);
+    });
+  }
+  if (!await schema.hasTable(lockTableName)) {
+    await schema.createTable(lockTableName, (table) => {
+      table.string("name").primaryKey();
+      table.string("owner");
+      table.bigInteger("expires_at");
+      table.index(["expires_at"], `${lockTableName.replaceAll(".", "_")}_expires_at_index`);
+    });
+  }
+}
+function renderCacheTableMigration(tableName = DEFAULT_CACHE_DATABASE_TABLE, lockTableName = DEFAULT_CACHE_DATABASE_LOCK_TABLE) {
+  return [
+    "import { defineMigration, type MigrationContext } from '@holo-js/db'",
+    "",
+    "export default defineMigration({",
+    "  async up({ schema }: MigrationContext) {",
+    `    await schema.createTable('${tableName}', (table) => {`,
+    "      table.string('key').primaryKey()",
+    "      table.text('payload')",
+    "      table.bigInteger('expires_at').nullable()",
+    `      table.index(['expires_at'], '${tableName.replaceAll(".", "_")}_expires_at_index')`,
+    "    })",
+    `    await schema.createTable('${lockTableName}', (table) => {`,
+    "      table.string('name').primaryKey()",
+    "      table.string('owner')",
+    "      table.bigInteger('expires_at')",
+    `      table.index(['expires_at'], '${lockTableName.replaceAll(".", "_")}_expires_at_index')`,
+    "    })",
+    "  },",
+    "  async down({ schema }: MigrationContext) {",
+    `    await schema.dropTable('${lockTableName}')`,
+    `    await schema.dropTable('${tableName}')`,
+    "  },",
+    "})",
+    ""
+  ].join("\n");
+}
+function resolveExecutionResultAffectedRows(result) {
+  return result.affectedRows ?? 0;
+}
+function isDatabaseCacheTableMissingError(error, tableName, lockTableName) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const message = error.message.toLowerCase();
+  const errorCode = typeof Reflect.get(error, "code") === "string" ? String(Reflect.get(error, "code")).toUpperCase() : void 0;
+  const mentionsCacheTable = message.includes(tableName.toLowerCase()) || message.includes(lockTableName.toLowerCase());
+  if (errorCode === "SQLITE_ERROR" || errorCode === "ER_NO_SUCH_TABLE" || errorCode === "42P01") {
+    return mentionsCacheTable || message.includes("no such table") || message.includes("does not exist");
+  }
+  return (message.includes("no such table") || message.includes("does not exist") || message.includes("doesn't exist")) && mentionsCacheTable;
+}
+function normalizeDatabaseCacheTableError(error, tableName, lockTableName) {
+  if (isDatabaseCacheTableMissingError(error, tableName, lockTableName)) {
+    throw new CacheConfigError(
+      `[@holo-js/cache] Database cache tables "${tableName}" and "${lockTableName}" are missing. Run "holo cache:table" and then "holo migrate".`,
+      { cause: error }
+    );
+  }
+  throw error;
+}
+async function withDatabaseCacheTableGuard(tableName, lockTableName, callback) {
+  try {
+    return await callback();
+  } catch (error) {
+    normalizeDatabaseCacheTableError(error, tableName, lockTableName);
+  }
+}
+async function readEntry(connection, tableName, key, now) {
+  const row = await new TableQueryBuilder(tableName, connection).where("key", key).first();
+  if (!row) {
+    return { state: "missing" };
+  }
+  if (typeof row.expires_at === "number" && row.expires_at <= now) {
+    await new TableQueryBuilder(tableName, connection).where("key", key).delete();
+    return { state: "missing" };
+  }
+  return {
+    state: "hit",
+    value: row
+  };
+}
+async function readLock(connection, tableName, name, now) {
+  const row = await new TableQueryBuilder(tableName, connection).where("name", name).first();
+  if (!row) {
+    return { state: "missing" };
+  }
+  if (row.expires_at <= now) {
+    await new TableQueryBuilder(tableName, connection).where("name", name).delete();
+    return { state: "missing" };
+  }
+  return {
+    state: "hit",
+    value: row
+  };
+}
+function createDatabaseLock(connection, tableName, entryTableName, name, seconds, now, sleep, ownerFactory) {
+  const owner = ownerFactory();
+  async function tryAcquire() {
+    return withDatabaseCacheTableGuard(entryTableName, tableName, async () => connection.transaction(async (tx) => {
+      const locks = new TableQueryBuilder(tableName, tx);
+      const existing = await readLock(tx, tableName, name, now());
+      if (existing.state === "hit") {
+        return false;
+      }
+      const inserted = await locks.insertOrIgnore({
+        name,
+        owner,
+        expires_at: now() + seconds * 1e3
+      });
+      return resolveExecutionResultAffectedRows(inserted) > 0;
+    }));
+  }
+  async function withCallback(callback) {
+    if (!callback) {
+      return true;
+    }
+    try {
+      return await callback();
+    } finally {
+      await lock.release();
+    }
+  }
+  const lock = {
+    name,
+    async get(callback) {
+      if (!await tryAcquire()) {
+        return false;
+      }
+      return withCallback(callback);
+    },
+    async release() {
+      const deleted = await withDatabaseCacheTableGuard(entryTableName, tableName, async () => connection.transaction(async (tx) => {
+        const current = await readLock(tx, tableName, name, now());
+        if (current.state === "missing" || current.value.owner !== owner) {
+          return 0;
+        }
+        return resolveExecutionResultAffectedRows(
+          await new TableQueryBuilder(tableName, tx).where("name", name).delete()
+        );
+      }));
+      return deleted > 0;
+    },
+    async block(waitSeconds, callback) {
+      const deadline = now() + waitSeconds * 1e3;
+      while (true) {
+        if (await tryAcquire()) {
+          return withCallback(callback);
+        }
+        if (now() >= deadline) {
+          return false;
+        }
+        await sleep(10);
+      }
+    }
+  };
+  return lock;
+}
+function createDatabaseCacheDriver(options) {
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? defaultSleep;
+  const ownerFactory = options.ownerFactory ?? randomUUID;
+  const connection = createDatabaseConnection(options.connectionName, options.connection);
+  const entryTableName = options.table;
+  const lockTableName = options.lockTable;
+  const prefix = options.prefix ?? "";
+  async function writeEntry(tx, input) {
+    await new TableQueryBuilder(entryTableName, tx).upsert({
+      key: input.key,
+      payload: input.payload,
+      expires_at: input.expiresAt ?? null
+    }, ["key"], ["payload", "expires_at"]);
+    return true;
+  }
+  async function mutateNumericValue(key, amount) {
+    const result = await createDatabaseLock(
+      connection,
+      lockTableName,
+      entryTableName,
+      `__numeric__:${key}`,
+      1,
+      now,
+      sleep,
+      ownerFactory
+    ).block(1, async () => {
+      return connection.transaction(async (tx) => {
+        const entry = await readEntry(tx, entryTableName, key, now());
+        const currentValue = entry.state === "hit" ? deserializeCacheValue(entry.value.payload) : 0;
+        if (typeof currentValue !== "number" || !Number.isFinite(currentValue)) {
+          throw new CacheInvalidNumericMutationError(`[@holo-js/cache] Cache key "${key}" does not contain a numeric value.`);
+        }
+        const nextValue = currentValue + amount;
+        await writeEntry(tx, {
+          key,
+          payload: serializeCacheValue(nextValue),
+          expiresAt: entry.state === "hit" ? entry.value.expires_at ?? void 0 : void 0
+        });
+        return nextValue;
+      });
+    });
+    if (result === false) {
+      throw new CacheLockAcquisitionError(`[@holo-js/cache] Could not acquire database cache mutation lock for "${key}".`);
+    }
+    if (result === true) {
+      throw new CacheLockAcquisitionError(`[@holo-js/cache] Database cache mutation lock for "${key}" returned no numeric result.`);
+    }
+    return result;
+  }
+  return {
+    name: options.name,
+    driver: "database",
+    async get(key) {
+      const entry = await withDatabaseCacheTableGuard(entryTableName, lockTableName, async () => {
+        return readEntry(connection, entryTableName, key, now());
+      });
+      if (entry.state === "missing") {
+        return Object.freeze({ hit: false });
+      }
+      return Object.freeze({
+        hit: true,
+        payload: entry.value.payload,
+        expiresAt: entry.value.expires_at ?? void 0
+      });
+    },
+    async put(input) {
+      return withDatabaseCacheTableGuard(entryTableName, lockTableName, async () => connection.transaction(async (tx) => {
+        return writeEntry(tx, input);
+      }));
+    },
+    async add(input) {
+      return withDatabaseCacheTableGuard(entryTableName, lockTableName, async () => connection.transaction(async (tx) => {
+        const existing = await readEntry(tx, entryTableName, input.key, now());
+        if (existing.state === "hit") {
+          return false;
+        }
+        const inserted = await new TableQueryBuilder(entryTableName, tx).insertOrIgnore({
+          key: input.key,
+          payload: input.payload,
+          expires_at: input.expiresAt ?? null
+        });
+        return resolveExecutionResultAffectedRows(inserted) > 0;
+      }));
+    },
+    async forget(key) {
+      return withDatabaseCacheTableGuard(entryTableName, lockTableName, async () => {
+        return resolveExecutionResultAffectedRows(
+          await new TableQueryBuilder(entryTableName, connection).where("key", key).delete()
+        ) > 0;
+      });
+    },
+    async flush() {
+      await withDatabaseCacheTableGuard(entryTableName, lockTableName, async () => connection.transaction(async (tx) => {
+        if (!prefix) {
+          await new TableQueryBuilder(lockTableName, tx).delete();
+          await new TableQueryBuilder(entryTableName, tx).delete();
+          return;
+        }
+        const hasSqlWildcard = /[%_[]/.test(prefix);
+        if (hasSqlWildcard) {
+          const upperBound = `${prefix}\uFFFF`;
+          await new TableQueryBuilder(lockTableName, tx).where("name", ">=", prefix).where("name", "<", upperBound).delete();
+          await new TableQueryBuilder(entryTableName, tx).where("key", ">=", prefix).where("key", "<", upperBound).delete();
+          return;
+        }
+        const likePattern = `${prefix}%`;
+        await new TableQueryBuilder(lockTableName, tx).whereLike("name", likePattern).delete();
+        await new TableQueryBuilder(entryTableName, tx).whereLike("key", likePattern).delete();
+      }));
+    },
+    async increment(key, amount) {
+      return mutateNumericValue(key, amount);
+    },
+    async decrement(key, amount) {
+      return mutateNumericValue(key, -amount);
+    },
+    lock(name, seconds) {
+      return createDatabaseLock(connection, lockTableName, entryTableName, name, seconds, now, sleep, ownerFactory);
+    }
+  };
+}
+var cacheDbInternals = {
+  createDatabaseConnection,
+  createDatabaseContextOptions,
+  defaultSleep,
+  isDatabaseCacheTableMissingError,
+  normalizeDatabaseCacheTableError,
+  prepareCacheDatabaseTables,
+  readEntry,
+  readLock,
+  renderCacheTableMigration,
+  resolveDriver,
+  withDatabaseCacheTableGuard
+};
+export {
+  DEFAULT_CACHE_DATABASE_LOCK_TABLE,
+  DEFAULT_CACHE_DATABASE_TABLE,
+  cacheDbInternals,
+  createDatabaseCacheDriver
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@holo-js/cache-db",
+  "version": "0.1.3",
+  "description": "Holo-JS Framework - DB-backed cache driver",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "stub": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest --run"
+  },
+  "peerDependencies": {
+    "@holo-js/cache": "^0.1.3",
+    "@holo-js/db": "^0.1.3"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@holo-js/cache": "workspace:*",
+    "@holo-js/db": "workspace:*",
+    "@types/node": "catalog:",
+    "tsup": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}