@framers/sql-storage-adapter 0.7.1 → 0.7.3

package/dist/cjs/core/contracts/extensions.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Extended types for advanced adapter features.
+ * These types are used by adapters that provide additional functionality
+ * beyond the core StorageAdapter interface.
+ */
+import type { BatchOperation as CoreBatchOperation } from './index.js';
+/**
+ * Performance metrics for monitoring adapter usage.
+ */
+export interface PerformanceMetrics {
+    totalQueries: number;
+    totalDuration: number;
+    averageDuration: number;
+    cacheHits?: number;
+    cacheMisses?: number;
+    slowQueries?: Array<{
+        query: string;
+        duration: number;
+        timestamp: Date;
+    }>;
+}
+/**
+ * Options for streaming large result sets.
+ */
+export interface StreamOptions {
+    batchSize?: number;
+    highWaterMark?: number;
+}
+/**
+ * Database migration definition.
+ */
+export interface Migration {
+    id: string;
+    version: number;
+    up: string;
+    down?: string;
+    description?: string;
+    appliedAt?: Date;
+}
+/**
+ * Extended batch operation with additional metadata.
+ * Used by adapters that support richer batch operation semantics.
+ */
+export interface ExtendedBatchOperation extends CoreBatchOperation {
+    type?: 'insert' | 'update' | 'delete';
+    table?: string;
+    values?: Record<string, unknown> | Array<Record<string, unknown>>;
+    where?: Record<string, unknown>;
+}
+/**
+ * Extended storage adapter interface for advanced features.
+ */
+export interface StorageAdapterExtensions {
+    /**
+     * Apply database migrations.
+     */
+    migrate?(migrations: Migration[]): Promise<void>;
+    /**
+     * Get migration status.
+     */
+    getMigrationStatus?(): Promise<Migration[]>;
+    /**
+     * Get performance metrics.
+     */
+    getMetrics?(): PerformanceMetrics;
+    /**
+     * Stream large result sets.
+     */
+    stream?<T>(statement: string, parameters?: unknown, options?: StreamOptions): AsyncIterableIterator<T>;
+}
+export type { BatchOperation } from './index.js';
+export type { BatchResult } from './index.js';
+//# sourceMappingURL=extensions.d.ts.map

package/dist/cjs/core/contracts/extensions.js

@@ -0,0 +1,15 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var extensions_exports = {};
+module.exports = __toCommonJS(extensions_exports);

package/dist/cjs/core/contracts/features.d.ts

@@ -0,0 +1,25 @@
+import type { SqlDialect } from './dialect.js';
+import type { IFullTextSearch } from './fts.js';
+import type { IBlobCodec } from './blobCodec.js';
+import type { IDatabaseExporter } from './exporter.js';
+import type { StorageAdapter } from './index.js';
+/**
+ * Bundle of platform-aware database features.
+ *
+ * Created by `createStorageFeatures(adapter)` — consumers use this
+ * instead of writing raw platform-specific SQL.
+ */
+export interface StorageFeatures {
+    readonly dialect: SqlDialect;
+    readonly fts: IFullTextSearch;
+    readonly blobCodec: IBlobCodec;
+    readonly exporter: IDatabaseExporter;
+}
+/**
+ * Create a platform-aware feature bundle for the given storage adapter.
+ *
+ * Inspects `adapter.kind` and the runtime environment to select the right
+ * dialect, FTS, BLOB codec, and exporter implementations.
+ */
+export declare function createStorageFeatures(adapter: StorageAdapter): StorageFeatures;
+//# sourceMappingURL=features.d.ts.map

package/dist/cjs/core/contracts/features.js

@@ -0,0 +1,61 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var features_exports = {};
+__export(features_exports, {
+  createStorageFeatures: () => createStorageFeatures
+});
+module.exports = __toCommonJS(features_exports);
+var import_SqliteDialect = require("../../dialects/SqliteDialect.js");
+var import_PostgresDialect = require("../../dialects/PostgresDialect.js");
+var import_SqliteFts5 = require("../../fts/SqliteFts5.js");
+var import_PostgresFts = require("../../fts/PostgresFts.js");
+var import_NodeBlobCodec = require("../../codecs/NodeBlobCodec.js");
+var import_BrowserBlobCodec = require("../../codecs/BrowserBlobCodec.js");
+var import_SqliteFileExporter = require("../../exporters/SqliteFileExporter.js");
+var import_PostgresExporter = require("../../exporters/PostgresExporter.js");
+function extractPostgresConnectionString(adapter) {
+  const options = adapter.options;
+  if (!options)
+    return void 0;
+  if (options.connectionString)
+    return options.connectionString;
+  if (!options.database)
+    return void 0;
+  const host = options.host ?? "localhost";
+  const port = options.port ?? 5432;
+  const user = options.user ? encodeURIComponent(options.user) : "";
+  const password = options.password ? `:${encodeURIComponent(options.password)}` : "";
+  const auth = user ? `${user}${password}@` : "";
+  const sslQuery = options.ssl ? "?sslmode=require" : "";
+  return `postgresql://${auth}${host}:${port}/${options.database}${sslQuery}`;
+}
+function createStorageFeatures(adapter) {
+  const isPostgres = adapter.kind === "postgres";
+  const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+  const postgresConnectionString = isPostgres ? extractPostgresConnectionString(adapter) : void 0;
+  return {
+    dialect: isPostgres ? new import_PostgresDialect.PostgresDialect() : new import_SqliteDialect.SqliteDialect(),
+    fts: isPostgres ? new import_PostgresFts.PostgresFts() : new import_SqliteFts5.SqliteFts5(),
+    blobCodec: isBrowser ? new import_BrowserBlobCodec.BrowserBlobCodec() : new import_NodeBlobCodec.NodeBlobCodec(),
+    exporter: isPostgres ? new import_PostgresExporter.PostgresExporter(postgresConnectionString) : new import_SqliteFileExporter.SqliteFileExporter(adapter)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createStorageFeatures
+});

package/dist/cjs/core/contracts/fts.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Full-text search abstraction.
+ *
+ * SQLite implementations use FTS5 virtual tables.
+ * Postgres implementations use tsvector columns with GIN indexes.
+ * Methods return SQL strings — no database calls.
+ */
+export interface IFullTextSearch {
+    /**
+     * Generate DDL to create the full-text search index.
+     *
+     * @param config.table - Name for the FTS index/virtual table.
+     * @param config.columns - Columns to index.
+     * @param config.contentTable - Source table (for external-content FTS5).
+     * @param config.tokenizer - Tokenizer config (e.g. 'porter ascii').
+     */
+    createIndex(config: {
+        table: string;
+        columns: string[];
+        contentTable?: string;
+        tokenizer?: string;
+    }): string;
+    /**
+     * Generate a WHERE clause fragment for full-text matching.
+     * SQLite: `memory_traces_fts MATCH ?`
+     * Postgres: `memory_traces._tsv @@ plainto_tsquery('english', $1)`
+     */
+    matchClause(indexName: string, queryPlaceholder: string): string;
+    /**
+     * Generate an ORDER BY rank expression.
+     * SQLite: `memory_traces_fts.rank`
+     * Postgres: `ts_rank(memory_traces._tsv, plainto_tsquery('english', $1))`
+     */
+    rankExpression(indexName: string, queryPlaceholder?: string): string;
+    /**
+     * Generate the rebuild/reindex command.
+     * SQLite: `INSERT INTO fts_table(fts_table) VALUES('rebuild')`
+     * Postgres: `UPDATE content_table SET _tsv = to_tsvector('english', col1 || ' ' || col2)`
+     */
+    rebuildCommand(indexName: string): string;
+    /**
+     * Generate an INSERT to sync external-content FTS after a row insert.
+     * SQLite: `INSERT INTO fts_table (rowid, col1, col2) VALUES (expr, ?, ?)`
+     * Postgres: `UPDATE content_table SET _tsv = to_tsvector(...) WHERE ...`
+     */
+    syncInsert(indexName: string, rowIdExpr: string, columns: string[]): string;
+    /**
+     * Sanitize natural-language input into a safe search query.
+     * SQLite: wraps words in quotes, strips FTS5 operators.
+     * Postgres: pass-through (plainto_tsquery handles it).
+     */
+    sanitizeQuery(input: string): string;
+    /**
+     * Generate a SELECT joining the FTS index to the content table.
+     * This handles the structural difference between FTS5 (separate virtual table
+     * joined via rowid) and Postgres (tsvector column on the content table itself).
+     *
+     * @param contentTable - The base table (e.g. 'memory_traces').
+     * @param contentAlias - Alias for the content table (e.g. 't').
+     * @param ftsAlias - Alias for the FTS table/column (e.g. 'fts').
+     * @param indexName - FTS index/virtual table name.
+     * @returns FROM/JOIN clause fragment.
+     */
+    joinClause(contentTable: string, contentAlias: string, ftsAlias: string, indexName: string): string;
+}
+//# sourceMappingURL=fts.d.ts.map

package/dist/cjs/core/contracts/fts.js

@@ -0,0 +1,15 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var fts_exports = {};
+module.exports = __toCommonJS(fts_exports);