@dexto/storage 1.6.0

package/dist/database/factory.d.cts

@@ -0,0 +1,42 @@
+import { Logger, Database } from '@dexto/core';
+import { z } from 'zod';
+
+/**
+ * Factory interface for creating database instances.
+ *
+ * Factories are plain exports (no global registries). Images decide which factories are
+ * available by including them in `image.storage.database`.
+ */
+interface DatabaseFactory<TConfig = unknown> {
+    /**
+     * Zod schema for validating factory-specific configuration.
+     * The schema must output the `TConfig` type.
+     */
+    configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>;
+    /**
+     * Factory function to create a Database instance.
+     *
+     * Database factories may return a Promise to support lazy loading of optional
+     * dependencies (e.g., `better-sqlite3`, `pg`).
+     *
+     * @param config - Validated configuration specific to this backend
+     * @param logger - Logger instance for the database
+     * @returns A Database implementation (or Promise for async backends)
+     */
+    create(config: TConfig, logger: Logger): Database | Promise<Database>;
+    /**
+     * Optional metadata for documentation, UIs, and discovery.
+     */
+    metadata?: {
+        /** Human-readable name (e.g., "SQLite", "PostgreSQL") */
+        displayName: string;
+        /** Brief description of this storage backend */
+        description: string;
+        /** Whether this backend requires network connectivity */
+        requiresNetwork?: boolean;
+        /** Whether this backend supports list operations (append/getRange) */
+        supportsListOperations?: boolean;
+    };
+}
+
+export type { DatabaseFactory };

package/dist/database/factory.d.ts

@@ -0,0 +1,41 @@
+import type { Database } from './types.js';
+import type { Logger } from '@dexto/core';
+import type { z } from 'zod';
+/**
+ * Factory interface for creating database instances.
+ *
+ * Factories are plain exports (no global registries). Images decide which factories are
+ * available by including them in `image.storage.database`.
+ */
+export interface DatabaseFactory<TConfig = unknown> {
+    /**
+     * Zod schema for validating factory-specific configuration.
+     * The schema must output the `TConfig` type.
+     */
+    configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>;
+    /**
+     * Factory function to create a Database instance.
+     *
+     * Database factories may return a Promise to support lazy loading of optional
+     * dependencies (e.g., `better-sqlite3`, `pg`).
+     *
+     * @param config - Validated configuration specific to this backend
+     * @param logger - Logger instance for the database
+     * @returns A Database implementation (or Promise for async backends)
+     */
+    create(config: TConfig, logger: Logger): Database | Promise<Database>;
+    /**
+     * Optional metadata for documentation, UIs, and discovery.
+     */
+    metadata?: {
+        /** Human-readable name (e.g., "SQLite", "PostgreSQL") */
+        displayName: string;
+        /** Brief description of this storage backend */
+        description: string;
+        /** Whether this backend requires network connectivity */
+        requiresNetwork?: boolean;
+        /** Whether this backend supports list operations (append/getRange) */
+        supportsListOperations?: boolean;
+    };
+}
+//# sourceMappingURL=factory.d.ts.map

package/dist/database/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/database/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,GAAG,OAAO;IAC9C;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAExD;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEtE;;OAEG;IACH,QAAQ,CAAC,EAAE;QACP,yDAAyD;QACzD,WAAW,EAAE,MAAM,CAAC;QACpB,gDAAgD;QAChD,WAAW,EAAE,MAAM,CAAC;QACpB,yDAAyD;QACzD,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,sEAAsE;QACtE,sBAAsB,CAAC,EAAE,OAAO,CAAC;KACpC,CAAC;CACL"}

package/dist/database/index.cjs

@@ -0,0 +1,46 @@
+"use strict";
+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 database_exports = {};
+__export(database_exports, {
+  DATABASE_TYPES: () => import_schemas.DATABASE_TYPES,
+  DatabaseConfigSchema: () => import_schemas.DatabaseConfigSchema,
+  InMemoryDatabaseSchema: () => import_schemas.InMemoryDatabaseSchema,
+  MemoryDatabaseStore: () => import_memory_database_store.MemoryDatabaseStore,
+  PostgresDatabaseSchema: () => import_schemas.PostgresDatabaseSchema,
+  SqliteDatabaseSchema: () => import_schemas.SqliteDatabaseSchema,
+  inMemoryDatabaseFactory: () => import_factories.inMemoryDatabaseFactory,
+  postgresDatabaseFactory: () => import_factories.postgresDatabaseFactory,
+  sqliteDatabaseFactory: () => import_factories.sqliteDatabaseFactory
+});
+module.exports = __toCommonJS(database_exports);
+var import_factories = require("./factories/index.js");
+var import_schemas = require("./schemas.js");
+var import_memory_database_store = require("./memory-database-store.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DATABASE_TYPES,
+  DatabaseConfigSchema,
+  InMemoryDatabaseSchema,
+  MemoryDatabaseStore,
+  PostgresDatabaseSchema,
+  SqliteDatabaseSchema,
+  inMemoryDatabaseFactory,
+  postgresDatabaseFactory,
+  sqliteDatabaseFactory
+});

package/dist/database/index.d.cts

@@ -0,0 +1,8 @@
+export { DatabaseFactory } from './factory.cjs';
+export { Database } from '@dexto/core';
+export { inMemoryDatabaseFactory } from './factories/memory.cjs';
+export { sqliteDatabaseFactory } from './factories/sqlite.cjs';
+export { postgresDatabaseFactory } from './factories/postgres.cjs';
+export { DATABASE_TYPES, DatabaseConfig, DatabaseConfigSchema, DatabaseType, InMemoryDatabaseConfig, InMemoryDatabaseSchema, PostgresDatabaseConfig, PostgresDatabaseSchema, SqliteDatabaseConfig, SqliteDatabaseSchema } from './schemas.cjs';
+export { MemoryDatabaseStore } from './memory-database-store.cjs';
+import 'zod';

package/dist/database/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Database Module
+ *
+ * This module provides a flexible database system with support for
+ * multiple backends through a factory pattern.
+ *
+ * ## Built-in Factories
+ * - `in-memory`: Store data in RAM (for testing/development)
+ * - `sqlite`: Store data in a local SQLite file
+ * - `postgres`: Store data in PostgreSQL server
+ *
+ * ## Custom Factories
+ * Product layers (CLI/server/platform) decide which factories are available by including them
+ * in images (`DextoImage.storage.database`).
+ *
+ * ## Usage
+ * Database backends are typically constructed by the product-layer resolver (`@dexto/agent-config`)
+ * via image-provided factory maps. For direct usage, call a factory's `create()` after validating
+ * config with its `configSchema`.
+ */
+export type { DatabaseFactory } from './factory.js';
+export type { Database } from './types.js';
+export { inMemoryDatabaseFactory, sqliteDatabaseFactory, postgresDatabaseFactory, } from './factories/index.js';
+export { DATABASE_TYPES, DatabaseConfigSchema, InMemoryDatabaseSchema, SqliteDatabaseSchema, PostgresDatabaseSchema, type DatabaseType, type DatabaseConfig, type InMemoryDatabaseConfig, type SqliteDatabaseConfig, type PostgresDatabaseConfig, } from './schemas.js';
+export { MemoryDatabaseStore } from './memory-database-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/database/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/database/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,EACH,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,GAC1B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACH,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC9B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/database/index.js

@@ -0,0 +1,24 @@
+import {
+  inMemoryDatabaseFactory,
+  sqliteDatabaseFactory,
+  postgresDatabaseFactory
+} from "./factories/index.js";
+import {
+  DATABASE_TYPES,
+  DatabaseConfigSchema,
+  InMemoryDatabaseSchema,
+  SqliteDatabaseSchema,
+  PostgresDatabaseSchema
+} from "./schemas.js";
+import { MemoryDatabaseStore } from "./memory-database-store.js";
+export {
+  DATABASE_TYPES,
+  DatabaseConfigSchema,
+  InMemoryDatabaseSchema,
+  MemoryDatabaseStore,
+  PostgresDatabaseSchema,
+  SqliteDatabaseSchema,
+  inMemoryDatabaseFactory,
+  postgresDatabaseFactory,
+  sqliteDatabaseFactory
+};

package/dist/database/memory-database-store.cjs

@@ -0,0 +1,121 @@
+"use strict";
+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 memory_database_store_exports = {};
+__export(memory_database_store_exports, {
+  MemoryDatabaseStore: () => MemoryDatabaseStore
+});
+module.exports = __toCommonJS(memory_database_store_exports);
+var import_core = require("@dexto/core");
+class MemoryDatabaseStore {
+  data = /* @__PURE__ */ new Map();
+  lists = /* @__PURE__ */ new Map();
+  connected = false;
+  async connect() {
+    if (this.connected) return;
+    this.connected = true;
+  }
+  async disconnect() {
+    this.connected = false;
+    this.data.clear();
+    this.lists.clear();
+  }
+  isConnected() {
+    return this.connected;
+  }
+  getStoreType() {
+    return "in-memory";
+  }
+  async get(key) {
+    this.checkConnection();
+    try {
+      return this.data.get(key);
+    } catch (error) {
+      throw import_core.StorageError.readFailed(
+        "get",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
+  async set(key, value) {
+    this.checkConnection();
+    try {
+      this.data.set(key, value);
+    } catch (error) {
+      throw import_core.StorageError.writeFailed(
+        "set",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
+  async delete(key) {
+    this.checkConnection();
+    this.data.delete(key);
+    this.lists.delete(key);
+  }
+  async list(prefix) {
+    this.checkConnection();
+    const keys = [];
+    for (const key of Array.from(this.data.keys())) {
+      if (key.startsWith(prefix)) {
+        keys.push(key);
+      }
+    }
+    for (const key of Array.from(this.lists.keys())) {
+      if (key.startsWith(prefix)) {
+        keys.push(key);
+      }
+    }
+    return Array.from(new Set(keys)).sort();
+  }
+  async append(key, item) {
+    this.checkConnection();
+    if (!this.lists.has(key)) {
+      this.lists.set(key, []);
+    }
+    this.lists.get(key).push(item);
+  }
+  async getRange(key, start, count) {
+    this.checkConnection();
+    const list = this.lists.get(key) || [];
+    return list.slice(start, start + count);
+  }
+  // Helper methods
+  checkConnection() {
+    if (!this.connected) {
+      throw import_core.StorageError.notConnected("MemoryDatabaseStore");
+    }
+  }
+  // Development helpers
+  async clear() {
+    this.data.clear();
+    this.lists.clear();
+  }
+  async dump() {
+    return {
+      data: Object.fromEntries(this.data.entries()),
+      lists: Object.fromEntries(this.lists.entries())
+    };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryDatabaseStore
+});

package/dist/database/memory-database-store.d.cts

@@ -0,0 +1,30 @@
+import { Database } from '@dexto/core';
+
+/**
+ * In-memory database store for development and testing.
+ * Supports list operations for message history and enumeration for settings.
+ * Data is lost when the process restarts.
+ */
+declare class MemoryDatabaseStore implements Database {
+    private data;
+    private lists;
+    private connected;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    append<T>(key: string, item: T): Promise<void>;
+    getRange<T>(key: string, start: number, count: number): Promise<T[]>;
+    private checkConnection;
+    clear(): Promise<void>;
+    dump(): Promise<{
+        data: Record<string, unknown>;
+        lists: Record<string, unknown[]>;
+    }>;
+}
+
+export { MemoryDatabaseStore };

package/dist/database/memory-database-store.d.ts

@@ -0,0 +1,28 @@
+import type { Database } from './types.js';
+/**
+ * In-memory database store for development and testing.
+ * Supports list operations for message history and enumeration for settings.
+ * Data is lost when the process restarts.
+ */
+export declare class MemoryDatabaseStore implements Database {
+    private data;
+    private lists;
+    private connected;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    append<T>(key: string, item: T): Promise<void>;
+    getRange<T>(key: string, start: number, count: number): Promise<T[]>;
+    private checkConnection;
+    clear(): Promise<void>;
+    dump(): Promise<{
+        data: Record<string, unknown>;
+        lists: Record<string, unknown[]>;
+    }>;
+}
+//# sourceMappingURL=memory-database-store.d.ts.map

package/dist/database/memory-database-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-database-store.d.ts","sourceRoot":"","sources":["../../src/database/memory-database-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,QAAQ;IAChD,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,SAAS,CAAS;IAEpB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAKxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,MAAM;IAIhB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAa3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAsBvC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9C,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAO1E,OAAO,CAAC,eAAe;IAOjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;KAAE,CAAC;CAM7F"}

package/dist/database/memory-database-store.js

@@ -0,0 +1,97 @@
+import { StorageError } from "@dexto/core";
+class MemoryDatabaseStore {
+  data = /* @__PURE__ */ new Map();
+  lists = /* @__PURE__ */ new Map();
+  connected = false;
+  async connect() {
+    if (this.connected) return;
+    this.connected = true;
+  }
+  async disconnect() {
+    this.connected = false;
+    this.data.clear();
+    this.lists.clear();
+  }
+  isConnected() {
+    return this.connected;
+  }
+  getStoreType() {
+    return "in-memory";
+  }
+  async get(key) {
+    this.checkConnection();
+    try {
+      return this.data.get(key);
+    } catch (error) {
+      throw StorageError.readFailed(
+        "get",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
+  async set(key, value) {
+    this.checkConnection();
+    try {
+      this.data.set(key, value);
+    } catch (error) {
+      throw StorageError.writeFailed(
+        "set",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
+  async delete(key) {
+    this.checkConnection();
+    this.data.delete(key);
+    this.lists.delete(key);
+  }
+  async list(prefix) {
+    this.checkConnection();
+    const keys = [];
+    for (const key of Array.from(this.data.keys())) {
+      if (key.startsWith(prefix)) {
+        keys.push(key);
+      }
+    }
+    for (const key of Array.from(this.lists.keys())) {
+      if (key.startsWith(prefix)) {
+        keys.push(key);
+      }
+    }
+    return Array.from(new Set(keys)).sort();
+  }
+  async append(key, item) {
+    this.checkConnection();
+    if (!this.lists.has(key)) {
+      this.lists.set(key, []);
+    }
+    this.lists.get(key).push(item);
+  }
+  async getRange(key, start, count) {
+    this.checkConnection();
+    const list = this.lists.get(key) || [];
+    return list.slice(start, start + count);
+  }
+  // Helper methods
+  checkConnection() {
+    if (!this.connected) {
+      throw StorageError.notConnected("MemoryDatabaseStore");
+    }
+  }
+  // Development helpers
+  async clear() {
+    this.data.clear();
+    this.lists.clear();
+  }
+  async dump() {
+    return {
+      data: Object.fromEntries(this.data.entries()),
+      lists: Object.fromEntries(this.lists.entries())
+    };
+  }
+}
+export {
+  MemoryDatabaseStore
+};