@lostgradient/weft 0.2.0

package/dist/storage/bun-sql.js

@@ -0,0 +1,575 @@
+// @bun
+// src/storage/bun-sql.ts
+import { Database } from "bun:sqlite";
+
+// src/storage/derived-operations.ts
+async function storageHasCore(storage, key) {
+  return await storage.get(key) !== null;
+}
+async function* storageKeysCore(storage, prefix, options) {
+  for await (const [key] of storage.scan(prefix, options)) {
+    yield key;
+  }
+}
+async function storageCountCore(storage, prefix) {
+  let count = 0;
+  for await (const _key of storageKeysCore(storage, prefix)) {
+    count++;
+  }
+  return count;
+}
+async function storageDeletePrefixCore(storage, prefix) {
+  const operations = [];
+  for await (const key of storageKeysCore(storage, prefix)) {
+    operations.push({ type: "delete", key });
+  }
+  if (operations.length === 0) {
+    return 0;
+  }
+  await storage.batch(operations);
+  return operations.length;
+}
+async function storageDeleteRangeCore(storage, prefix, options) {
+  const operations = [];
+  for await (const key of storageKeysCore(storage, prefix, options)) {
+    operations.push({ type: "delete", key });
+  }
+  if (operations.length === 0) {
+    return 0;
+  }
+  await storage.batch(operations);
+  return operations.length;
+}
+
+// src/storage/capabilities.ts
+function requireStorageCapability(storage, capability, featureName) {
+  if (!storage.capabilities()[capability]) {
+    throw new Error(`Feature "${featureName}" requires storage capability "${capability}", but this storage backend does not provide it.`);
+  }
+}
+
+// src/storage/interface.ts
+function resolvePrefixRangeEnd(prefix) {
+  return prefix.length > 0 ? prefix.slice(0, -1) + String.fromCharCode(prefix.charCodeAt(prefix.length - 1) + 1) : "\xFF";
+}
+function storageValuesEqual(left, right) {
+  if (left === null || right === null) {
+    return left === right;
+  }
+  if (left.byteLength !== right.byteLength) {
+    return false;
+  }
+  for (let index = 0;index < left.byteLength; index++) {
+    if (left[index] !== right[index]) {
+      return false;
+    }
+  }
+  return true;
+}
+async function storageHas(storage, key) {
+  if (storage.has) {
+    return storage.has(key);
+  }
+  return storageHasCore(storage, key);
+}
+function storageKeys(storage, prefix, options) {
+  if (storage.keys) {
+    return storage.keys(prefix, options);
+  }
+  return storageKeysCore(storage, prefix, options);
+}
+async function storageCount(storage, prefix) {
+  if (storage.count) {
+    return storage.count(prefix);
+  }
+  return storageCountCore(storage, prefix);
+}
+async function storageDeletePrefix(storage, prefix) {
+  if (storage.deletePrefix) {
+    return storage.deletePrefix(prefix);
+  }
+  return storageDeletePrefixCore(storage, prefix);
+}
+async function storageConditionalBatch(storage, conditions, operations) {
+  requireStorageCapability(storage, "conditionalBatch", "storageConditionalBatch");
+  if (!storage.conditionalBatch) {
+    throw new Error("This storage backend reports conditionalBatch capability but does not implement the conditionalBatch() method.");
+  }
+  return storage.conditionalBatch(conditions, operations);
+}
+
+// src/storage/delete-range.ts
+function normalizeDeleteRangeLimit(limit) {
+  if (limit === undefined) {
+    return;
+  }
+  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 0) {
+    throw new Error("deleteRange limit must be a finite non-negative integer");
+  }
+  return limit === 0 ? 0 : limit;
+}
+function normalizeDeleteRangeOptions(options) {
+  const normalized = {};
+  let hasBound = false;
+  for (const bound of ["gt", "gte", "lt", "lte"]) {
+    const value = options[bound];
+    if (value === undefined) {
+      continue;
+    }
+    if (typeof value !== "string") {
+      throw new Error("deleteRange bounds must be strings");
+    }
+    normalized[bound] = value;
+    hasBound = true;
+  }
+  if (!hasBound) {
+    throw new Error("deleteRange requires at least one of gt/gte/lt/lte; use deletePrefix to delete a whole prefix");
+  }
+  const limit = normalizeDeleteRangeLimit(options.limit);
+  if (limit !== undefined) {
+    normalized.limit = limit;
+  }
+  return normalized;
+}
+async function storageDeleteRange(storage, prefix, options) {
+  const normalized = normalizeDeleteRangeOptions(options);
+  if (storage.deleteRange) {
+    return storage.deleteRange(prefix, normalized);
+  }
+  return storageDeleteRangeCore(storage, prefix, normalized);
+}
+
+// src/storage/read-only-query.ts
+var pragmaStatementPattern = /^PRAGMA\b/iu;
+var readOnlyPragmaPattern = /^PRAGMA\s+(?:[A-Z_][A-Z0-9_]*\.)?[A-Z_][A-Z0-9_]*\s*$/iu;
+var selectStatementPattern = /^SELECT\b/iu;
+function normalizeSql(sql) {
+  return sql.trim().replace(/;+\s*$/u, "").trim();
+}
+function isReadOnlyPragma(sql) {
+  return readOnlyPragmaPattern.test(sql);
+}
+function assertReadOnlyQuery(sql) {
+  const normalizedSql = normalizeSql(sql);
+  if (normalizedSql.length === 0) {
+    throw new Error("Storage query must not be empty.");
+  }
+  if (normalizedSql.includes(";")) {
+    throw new Error("Storage query must contain exactly one read-only statement.");
+  }
+  if (selectStatementPattern.test(normalizedSql)) {
+    return;
+  }
+  if (pragmaStatementPattern.test(normalizedSql) && isReadOnlyPragma(normalizedSql)) {
+    return;
+  }
+  throw new Error("Storage query only supports read-only SELECT and PRAGMA statements.");
+}
+
+// src/storage/scoped-storage.ts
+function normalizeScopePrefix(prefix) {
+  return prefix.replaceAll(/:+$/g, "");
+}
+function joinScopePrefixes(leftPrefix, rightPrefix) {
+  const normalizedLeftPrefix = normalizeScopePrefix(leftPrefix);
+  const normalizedRightPrefix = normalizeScopePrefix(rightPrefix);
+  if (normalizedLeftPrefix.length === 0) {
+    return normalizedRightPrefix;
+  }
+  if (normalizedRightPrefix.length === 0) {
+    return normalizedLeftPrefix;
+  }
+  return `${normalizedLeftPrefix}:${normalizedRightPrefix}`;
+}
+
+class ScopedStorage {
+  #storage;
+  #scopePrefix;
+  constructor(storage, prefix) {
+    this.#storage = storage;
+    this.#scopePrefix = normalizeScopePrefix(prefix);
+  }
+  #toInnerKey(key) {
+    if (this.#scopePrefix.length === 0) {
+      return key;
+    }
+    return key.length === 0 ? `${this.#scopePrefix}:` : `${this.#scopePrefix}:${key}`;
+  }
+  #toPublicKey(key) {
+    if (this.#scopePrefix.length === 0) {
+      return key;
+    }
+    return key.slice(this.#scopePrefix.length + 1);
+  }
+  #toInnerOptions(options = {}) {
+    const innerOptions = {};
+    if (options.limit !== undefined) {
+      innerOptions.limit = options.limit;
+    }
+    if (options.reverse !== undefined) {
+      innerOptions.reverse = options.reverse;
+    }
+    if (options.gt !== undefined) {
+      innerOptions.gt = this.#toInnerKey(options.gt);
+    }
+    if (options.gte !== undefined) {
+      innerOptions.gte = this.#toInnerKey(options.gte);
+    }
+    if (options.lt !== undefined) {
+      innerOptions.lt = this.#toInnerKey(options.lt);
+    }
+    if (options.lte !== undefined) {
+      innerOptions.lte = this.#toInnerKey(options.lte);
+    }
+    return innerOptions;
+  }
+  #toInnerDeleteRangeOptions(options) {
+    const innerOptions = {};
+    if (options.limit !== undefined) {
+      innerOptions.limit = options.limit;
+    }
+    if (options.gt !== undefined) {
+      innerOptions.gt = this.#toInnerKey(options.gt);
+    }
+    if (options.gte !== undefined) {
+      innerOptions.gte = this.#toInnerKey(options.gte);
+    }
+    if (options.lt !== undefined) {
+      innerOptions.lt = this.#toInnerKey(options.lt);
+    }
+    if (options.lte !== undefined) {
+      innerOptions.lte = this.#toInnerKey(options.lte);
+    }
+    return innerOptions;
+  }
+  capabilities() {
+    return this.#storage.capabilities();
+  }
+  scoped(prefix) {
+    return new ScopedStorage(this.#storage, joinScopePrefixes(this.#scopePrefix, prefix));
+  }
+  async get(key) {
+    return this.#storage.get(this.#toInnerKey(key));
+  }
+  async put(key, value) {
+    await this.#storage.put(this.#toInnerKey(key), value);
+  }
+  async delete(key) {
+    await this.#storage.delete(this.#toInnerKey(key));
+  }
+  async* scan(prefix, options) {
+    for await (const [key, value] of this.#storage.scan(this.#toInnerKey(prefix), this.#toInnerOptions(options))) {
+      yield [this.#toPublicKey(key), value];
+    }
+  }
+  async batch(operations) {
+    await this.#storage.batch(operations.map((operation) => {
+      if (operation.type === "put") {
+        return {
+          type: "put",
+          key: this.#toInnerKey(operation.key),
+          value: operation.value
+        };
+      }
+      return {
+        type: "delete",
+        key: this.#toInnerKey(operation.key)
+      };
+    }));
+  }
+  async conditionalBatch(conditions, operations) {
+    return storageConditionalBatch(this.#storage, conditions.map((condition) => ({
+      key: this.#toInnerKey(condition.key),
+      expectedValue: condition.expectedValue
+    })), operations.map((operation) => {
+      if (operation.type === "put") {
+        return {
+          type: "put",
+          key: this.#toInnerKey(operation.key),
+          value: operation.value
+        };
+      }
+      return {
+        type: "delete",
+        key: this.#toInnerKey(operation.key)
+      };
+    }));
+  }
+  async has(key) {
+    return storageHas(this.#storage, this.#toInnerKey(key));
+  }
+  async deletePrefix(prefix) {
+    return storageDeletePrefix(this.#storage, this.#toInnerKey(prefix));
+  }
+  async deleteRange(prefix, options) {
+    const inner = this.#toInnerDeleteRangeOptions(normalizeDeleteRangeOptions(options));
+    return storageDeleteRange(this.#storage, this.#toInnerKey(prefix), inner);
+  }
+  async* keys(prefix, options) {
+    for await (const key of storageKeys(this.#storage, this.#toInnerKey(prefix), this.#toInnerOptions(options))) {
+      yield this.#toPublicKey(key);
+    }
+  }
+  async count(prefix) {
+    return storageCount(this.#storage, this.#toInnerKey(prefix));
+  }
+  [Symbol.dispose]() {
+    this.#storage[Symbol.dispose]();
+  }
+}
+function scopedStorage(storage, prefix) {
+  return new ScopedStorage(storage, prefix);
+}
+
+// src/storage/sqlite-key-value-queries.ts
+var SQLITE_CREATE_KEY_VALUE_TABLE = `CREATE TABLE IF NOT EXISTS kv (
+  key TEXT PRIMARY KEY,
+  value BLOB NOT NULL
+) WITHOUT ROWID`;
+var SQLITE_SELECT_VALUE_BY_KEY = "SELECT value FROM kv WHERE key = ?";
+var SQLITE_UPSERT_VALUE_BY_KEY = "INSERT INTO kv (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value";
+var SQLITE_DELETE_VALUE_BY_KEY = "DELETE FROM kv WHERE key = ?";
+var SQLITE_SELECT_KEY_PRESENCE = "SELECT 1 AS present FROM kv WHERE key = ? LIMIT 1";
+var SQLITE_COUNT_KEYS_BY_PREFIX = "SELECT COUNT(*) AS count FROM kv WHERE key >= ? AND key < ?";
+var SQLITE_DELETE_KEYS_BY_PREFIX = "DELETE FROM kv WHERE key >= ? AND key < ?";
+function buildSqlitePrefixRangeParameters(prefix) {
+  return [prefix, resolvePrefixRangeEnd(prefix)];
+}
+function buildSqliteKeyRangeConditions(prefix, bounds) {
+  const { gt, gte, lt, lte } = bounds;
+  const conditions = ["key >= ? AND key < ?"];
+  const parameters = buildSqlitePrefixRangeParameters(prefix);
+  if (gt !== undefined) {
+    conditions.push("key > ?");
+    parameters.push(gt);
+  }
+  if (gte !== undefined) {
+    conditions.push("key >= ?");
+    parameters.push(gte);
+  }
+  if (lt !== undefined) {
+    conditions.push("key < ?");
+    parameters.push(lt);
+  }
+  if (lte !== undefined) {
+    conditions.push("key <= ?");
+    parameters.push(lte);
+  }
+  return { conditions, parameters };
+}
+function buildSqliteKeyRangeQuery(prefix, options = {}) {
+  const { limit, reverse } = options;
+  const { conditions, parameters } = buildSqliteKeyRangeConditions(prefix, options);
+  const direction = reverse ? "DESC" : "ASC";
+  const limitClause = limit !== undefined ? " LIMIT ?" : "";
+  if (limit !== undefined) {
+    parameters.push(limit);
+  }
+  return {
+    parameters,
+    sqlSuffix: `WHERE ${conditions.join(" AND ")} ORDER BY key ${direction}${limitClause}`
+  };
+}
+function buildSqliteKeyRangeDelete(prefix, options) {
+  const { conditions, parameters } = buildSqliteKeyRangeConditions(prefix, options);
+  const whereClause = conditions.join(" AND ");
+  if (options.limit === undefined) {
+    return {
+      parameters,
+      sql: `DELETE FROM kv WHERE ${whereClause}`
+    };
+  }
+  parameters.push(options.limit);
+  return {
+    parameters,
+    sql: `DELETE FROM kv WHERE key IN (SELECT key FROM kv WHERE ${whereClause} ORDER BY key ASC LIMIT ?)`
+  };
+}
+function buildSqliteKeyValueRangeSelect(prefix, options = {}) {
+  const { parameters, sqlSuffix } = buildSqliteKeyRangeQuery(prefix, options);
+  return {
+    parameters,
+    sql: `SELECT key, value FROM kv ${sqlSuffix}`
+  };
+}
+function buildSqliteKeyRangeSelect(prefix, options = {}) {
+  const { parameters, sqlSuffix } = buildSqliteKeyRangeQuery(prefix, options);
+  return {
+    parameters,
+    sql: `SELECT key FROM kv ${sqlSuffix}`
+  };
+}
+
+// src/storage/bun-sql.ts
+class BunSQLiteStorage {
+  #database;
+  #persistence;
+  #getStatement;
+  #putStatement;
+  #deleteStatement;
+  #hasStatement;
+  #countStatement;
+  #deletePrefixStatement;
+  #batchTransaction;
+  #scanStatements = new Map;
+  #keyStatements = new Map;
+  #deleteRangeStatements = new Map;
+  get scanStatementCacheSize() {
+    return this.#scanStatements.size;
+  }
+  constructor(path = ":memory:") {
+    this.#persistence = path === ":memory:" ? "ephemeral" : "local";
+    this.#database = new Database(path);
+    this.#database.exec("PRAGMA journal_mode = WAL");
+    this.#database.exec("PRAGMA synchronous = NORMAL");
+    this.#database.exec("PRAGMA cache_size = -64000");
+    this.#database.exec("PRAGMA mmap_size = 268435456");
+    this.#database.exec("PRAGMA temp_store = MEMORY");
+    this.#database.exec("PRAGMA wal_autocheckpoint = 10000");
+    this.#database.exec(SQLITE_CREATE_KEY_VALUE_TABLE);
+    this.#getStatement = this.#database.prepare(SQLITE_SELECT_VALUE_BY_KEY);
+    this.#putStatement = this.#database.prepare(SQLITE_UPSERT_VALUE_BY_KEY);
+    this.#deleteStatement = this.#database.prepare(SQLITE_DELETE_VALUE_BY_KEY);
+    this.#hasStatement = this.#database.prepare(SQLITE_SELECT_KEY_PRESENCE);
+    this.#countStatement = this.#database.prepare(SQLITE_COUNT_KEYS_BY_PREFIX);
+    this.#deletePrefixStatement = this.#database.prepare(SQLITE_DELETE_KEYS_BY_PREFIX);
+    this.#batchTransaction = this.#database.transaction((entries) => {
+      for (const entry of entries) {
+        if (entry.type === "put") {
+          this.#putStatement.run(entry.key, entry.value);
+        } else {
+          this.#deleteStatement.run(entry.key);
+        }
+      }
+    });
+  }
+  capabilities() {
+    return {
+      persistence: this.#persistence,
+      readAfterWrite: "linearizable",
+      scanConsistency: "snapshot",
+      atomicBatch: true,
+      conditionalBatch: true,
+      boundedRangeDelete: true
+    };
+  }
+  async get(key) {
+    const row = this.#getStatement.get(key);
+    if (!row)
+      return null;
+    return new Uint8Array(row.value);
+  }
+  async put(key, value) {
+    this.#putStatement.run(key, value);
+  }
+  async delete(key) {
+    this.#deleteStatement.run(key);
+  }
+  async has(key) {
+    return this.#hasStatement.get(key) != null;
+  }
+  async deletePrefix(prefix) {
+    const [rangeStart, rangeEnd] = buildSqlitePrefixRangeParameters(prefix);
+    return this.#deletePrefixStatement.run(rangeStart, rangeEnd).changes;
+  }
+  async deleteRange(prefix, options) {
+    const normalized = normalizeDeleteRangeOptions(options);
+    const { parameters, sql } = buildSqliteKeyRangeDelete(prefix, normalized);
+    let statement = this.#deleteRangeStatements.get(sql);
+    if (!statement) {
+      statement = this.#database.prepare(sql);
+      this.#deleteRangeStatements.set(sql, statement);
+    }
+    return statement.run(...parameters).changes;
+  }
+  async* scan(prefix, options = {}) {
+    const { parameters, sql } = buildSqliteKeyValueRangeSelect(prefix, options);
+    let statement = this.#scanStatements.get(sql);
+    if (!statement) {
+      statement = this.#database.prepare(sql);
+      this.#scanStatements.set(sql, statement);
+    }
+    const rows = statement.all(...parameters);
+    for (const row of rows) {
+      yield [row.key, new Uint8Array(row.value)];
+    }
+  }
+  async* keys(prefix, options = {}) {
+    const { parameters, sql } = buildSqliteKeyRangeSelect(prefix, options);
+    let statement = this.#keyStatements.get(sql);
+    if (!statement) {
+      statement = this.#database.prepare(sql);
+      this.#keyStatements.set(sql, statement);
+    }
+    for (const row of statement.all(...parameters)) {
+      yield row.key;
+    }
+  }
+  async count(prefix) {
+    const [rangeStart, rangeEnd] = buildSqlitePrefixRangeParameters(prefix);
+    return this.#countStatement.get(rangeStart, rangeEnd)?.count ?? 0;
+  }
+  scoped(prefix) {
+    const scoped = scopedStorage(this, prefix);
+    return scoped;
+  }
+  async batch(operations) {
+    if (operations.length === 0)
+      return;
+    this.#batchTransaction(operations);
+  }
+  async conditionalBatch(conditions, operations) {
+    const conditionalTransaction = this.#database.transaction((pendingConditions, pendingOperations) => {
+      for (const condition of pendingConditions) {
+        const row = this.#getStatement.get(condition.key);
+        const currentValue = row ? new Uint8Array(row.value) : null;
+        if (!storageValuesEqual(currentValue, condition.expectedValue)) {
+          return false;
+        }
+      }
+      for (const operation of pendingOperations) {
+        if (operation.type === "put") {
+          this.#putStatement.run(operation.key, operation.value);
+        } else {
+          this.#deleteStatement.run(operation.key);
+        }
+      }
+      return true;
+    });
+    return conditionalTransaction(conditions, operations);
+  }
+  async query(sql, parameters) {
+    assertReadOnlyQuery(sql);
+    const statement = this.#database.prepare(sql);
+    try {
+      return statement.all(...parameters ?? []);
+    } finally {
+      statement.finalize();
+    }
+  }
+  [Symbol.dispose]() {
+    this.#getStatement.finalize();
+    this.#putStatement.finalize();
+    this.#deleteStatement.finalize();
+    this.#hasStatement.finalize();
+    this.#countStatement.finalize();
+    this.#deletePrefixStatement.finalize();
+    for (const statement of this.#scanStatements.values()) {
+      statement.finalize();
+    }
+    this.#scanStatements.clear();
+    for (const statement of this.#keyStatements.values()) {
+      statement.finalize();
+    }
+    this.#keyStatements.clear();
+    for (const statement of this.#deleteRangeStatements.values()) {
+      statement.finalize();
+    }
+    this.#deleteRangeStatements.clear();
+    this.#database.close();
+  }
+}
+export {
+  BunSQLiteStorage as SQLiteStorage,
+  BunSQLiteStorage
+};

package/dist/storage/byte-encoding.d.ts

@@ -0,0 +1,6 @@
+export declare function encodeBytesToBase64(value: Uint8Array): string;
+/**
+ * Decode base64 storage bytes without relying on Node-only Buffer APIs.
+ */
+export declare function decodeBase64ToBytes(value: string): Uint8Array;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/storage/byte-encoding.js

@@ -0,0 +1,16 @@
+const BYTE_STRING_CHUNK_SIZE = 512;
+export function encodeBytesToBase64(value) {
+  const chunks = [];
+  for (let offset = 0;offset < value.length; offset += BYTE_STRING_CHUNK_SIZE)
+    chunks.push(String.fromCharCode(...value.subarray(offset, offset + BYTE_STRING_CHUNK_SIZE)));
+  return btoa(chunks.join(""));
+}
+export function decodeBase64ToBytes(value) {
+  const binary = atob(value), bytes = new Uint8Array(binary.length);
+  for (let index = 0;index < binary.length; index += 1)
+    bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+export function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}