@dexto/storage 1.7.2 → 1.8.0

package/README.md

@@ -1,38 +1,73 @@
 # `@dexto/storage`
 
-Concrete storage backends (blob store, database, cache) and their config schemas/factories.
+Concrete Node storage helpers and config schemas for images that choose to build `DextoStores`
+from local backends.
 
-Core (`@dexto/core`) owns the **interfaces** (`BlobStore`, `Database`, `Cache`) and `StorageManager`.
-Product layers (CLI/server/apps) choose which concrete backends are available by including factories
-in an image (`DextoImage.storage.*`) and resolving config via `@dexto/agent-config`.
+Core (`@dexto/core`) owns typed domain store contracts such as `ConversationStore`,
+`SessionStore`, `MemoryStore`, `ArtifactStore`, and `ToolStateStore`. This package provides Node
+backend implementations that image implementations can use internally to compose a `DextoStores`
+implementation.
+
+Product layers (CLI/server/apps) can either use these helpers inside an image or provide a
+native `DextoStores` implementation directly. Core code should depend on typed stores, not these
+backend helper classes.
 
 ## What this package exports
 
-- **Factories** (for image modules):
-  - Blob: `localBlobStoreFactory`, `inMemoryBlobStoreFactory`
-  - Database: `sqliteDatabaseFactory`, `postgresDatabaseFactory`, `inMemoryDatabaseFactory`
-  - Cache: `inMemoryCacheFactory`, `redisCacheFactory`
 - **Schemas** (for config parsing + UI):
   - Import from `@dexto/storage/schemas` for browser-safe schema-only exports.
 - **Concrete implementations** (Node runtime):
   - `LocalBlobStore`, `MemoryBlobStore`, `SQLiteStore`, `PostgresStore`, `RedisStore`, etc.
 
-## Using factories in an image
+## Using helpers in an image
 
 ```ts
 import type { DextoImage } from '@dexto/agent-config';
 import {
-  localBlobStoreFactory,
-  sqliteDatabaseFactory,
-  inMemoryCacheFactory,
+  BackendDextoStores,
+  DatabaseBackedArtifactStore,
+  DatabaseBackedSessionStore,
+  // ...other typed store adapters
+} from '@dexto/core/storage';
+import {
+  StorageSchema,
+  LocalBlobStore,
+  LocalBlobStoreSchema,
+  SQLiteStore,
+  SqliteDatabaseSchema,
+  MemoryCacheStore,
 } from '@dexto/storage';
 
 export const myImage: DextoImage = {
   /* metadata/defaults/tools/hooks/compaction/logger ... */
   storage: {
-    blob: { local: localBlobStoreFactory },
-    database: { sqlite: sqliteDatabaseFactory },
-    cache: { 'in-memory': inMemoryCacheFactory },
+    configSchema: StorageSchema,
+    async createStores(config, logger) {
+      const blobStore = new LocalBlobStore(LocalBlobStoreSchema.parse(config.blob), logger);
+      const database = new SQLiteStore(SqliteDatabaseSchema.parse(config.database), logger);
+      const cache = new MemoryCacheStore();
+
+      return new BackendDextoStores(
+        {
+          sessions: new DatabaseBackedSessionStore(database, cache),
+          artifacts: new DatabaseBackedArtifactStore(blobStore),
+          // ...provide every DextoStoreMap domain
+        },
+        {
+          async connect() {
+            await cache.connect();
+            await database.connect();
+            await blobStore.connect();
+          },
+          async disconnect() {
+            await Promise.all([cache.disconnect(), database.disconnect(), blobStore.disconnect()]);
+          },
+          isConnected() {
+            return cache.isConnected() && database.isConnected() && blobStore.isConnected();
+          },
+        },
+      );
+    },
   },
 };
 ```
@@ -55,26 +90,4 @@ storage:
 ```
 
 Those envelope schemas use `.passthrough()` so extra fields survive initial parsing. Detailed
-validation happens later in `@dexto/agent-config` by selecting the right factory from the loaded
-image and validating against that factory’s `configSchema`.
-
-## Optional dependencies
-
-Some backends rely on optional peer dependencies:
-
-- SQLite: `better-sqlite3`
-- Postgres: `pg`
-- Redis: `ioredis`
-
-Factories load these lazily and throw an actionable error if the dependency is missing.
-
-## Browser safety
-
-If you only need schemas/types (e.g., WebUI), import from:
-
-```ts
-import { StorageSchema } from '@dexto/storage/schemas';
-```
-
-Do not import from `@dexto/storage` in browser bundles, since the root entry also exports Node
-implementations.
+validation happens later inside the loaded image's `storage.createStores(...)` implementation.

package/dist/blob/index.cjs

@@ -23,12 +23,9 @@ __export(blob_exports, {
   InMemoryBlobStoreSchema: () => import_schemas.InMemoryBlobStoreSchema,
   LocalBlobStore: () => import_local_blob_store.LocalBlobStore,
   LocalBlobStoreSchema: () => import_schemas.LocalBlobStoreSchema,
-  MemoryBlobStore: () => import_memory_blob_store.MemoryBlobStore,
-  inMemoryBlobStoreFactory: () => import_factories.inMemoryBlobStoreFactory,
-  localBlobStoreFactory: () => import_factories.localBlobStoreFactory
+  MemoryBlobStore: () => import_memory_blob_store.MemoryBlobStore
 });
 module.exports = __toCommonJS(blob_exports);
-var import_factories = require("./factories/index.js");
 var import_schemas = require("./schemas.js");
 var import_local_blob_store = require("./local-blob-store.js");
 var import_memory_blob_store = require("./memory-blob-store.js");
@@ -39,7 +36,5 @@ var import_memory_blob_store = require("./memory-blob-store.js");
   InMemoryBlobStoreSchema,
   LocalBlobStore,
   LocalBlobStoreSchema,
-  MemoryBlobStore,
-  inMemoryBlobStoreFactory,
-  localBlobStoreFactory
+  MemoryBlobStore
 });

package/dist/blob/index.d.ts

@@ -2,24 +2,13 @@
  * Blob Storage Module
  *
  * This module provides a flexible blob storage system with support for
- * multiple backends through a factory pattern.
- *
- * ## Built-in Factories
- * - `local`: Store blobs on the local filesystem
- * - `in-memory`: Store blobs in RAM (for testing/development)
- *
- * ## Custom Factories
- * Product layers (CLI/server/platform) decide which factories are available by including them
- * in images (`DextoImage.storage.blob`).
+ * multiple concrete backends.
  *
  * ## Usage
- * Blob stores 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`.
+ * Blob stores are typically constructed by an image's storage implementation after validating
+ * config with the matching schema.
  */
-export type { BlobStoreFactory } from './factory.js';
 export type { BlobStore, BlobInput, BlobMetadata, BlobReference, BlobData, BlobStats, StoredBlobMetadata, } from './types.js';
-export { localBlobStoreFactory, inMemoryBlobStoreFactory } from './factories/index.js';
 export { BLOB_STORE_TYPES, BlobStoreConfigSchema, InMemoryBlobStoreSchema, LocalBlobStoreSchema, type BlobStoreType, type BlobStoreConfig, type InMemoryBlobStoreConfigInput, type InMemoryBlobStoreConfig, type LocalBlobStoreConfigInput, type LocalBlobStoreConfig, } from './schemas.js';
 export { LocalBlobStore } from './local-blob-store.js';
 export { MemoryBlobStore } from './memory-blob-store.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blob/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,YAAY,EACR,SAAS,EACT,SAAS,EACT,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,SAAS,EACT,kBAAkB,GACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAGvF,OAAO,EACH,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,GAC5B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blob/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EACR,SAAS,EACT,SAAS,EACT,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,SAAS,EACT,kBAAkB,GACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACH,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,GAC5B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/blob/index.js

@@ -1,4 +1,3 @@
-import { localBlobStoreFactory, inMemoryBlobStoreFactory } from "./factories/index.js";
 import {
   BLOB_STORE_TYPES,
   BlobStoreConfigSchema,
@@ -13,7 +12,5 @@ export {
   InMemoryBlobStoreSchema,
   LocalBlobStore,
   LocalBlobStoreSchema,
-  MemoryBlobStore,
-  inMemoryBlobStoreFactory,
-  localBlobStoreFactory
+  MemoryBlobStore
 };

package/dist/cache/index.cjs

@@ -23,13 +23,12 @@ __export(cache_exports, {
   InMemoryCacheSchema: () => import_schemas.InMemoryCacheSchema,
   MemoryCacheStore: () => import_memory_cache_store.MemoryCacheStore,
   RedisCacheSchema: () => import_schemas.RedisCacheSchema,
-  inMemoryCacheFactory: () => import_factories.inMemoryCacheFactory,
-  redisCacheFactory: () => import_factories.redisCacheFactory
+  RedisStore: () => import_redis_store.RedisStore
 });
 module.exports = __toCommonJS(cache_exports);
-var import_factories = require("./factories/index.js");
 var import_schemas = require("./schemas.js");
 var import_memory_cache_store = require("./memory-cache-store.js");
+var import_redis_store = require("./redis-store.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CACHE_TYPES,
@@ -37,6 +36,5 @@ var import_memory_cache_store = require("./memory-cache-store.js");
   InMemoryCacheSchema,
   MemoryCacheStore,
   RedisCacheSchema,
-  inMemoryCacheFactory,
-  redisCacheFactory
+  RedisStore
 });

package/dist/cache/index.d.ts

@@ -2,24 +2,14 @@
  * Cache Module
  *
  * This module provides a flexible caching system with support for
- * multiple backends through a factory pattern.
- *
- * ## Built-in Factories
- * - `in-memory`: Store data in RAM (for testing/development)
- * - `redis`: Store data in Redis server
- *
- * ## Custom Factories
- * Product layers (CLI/server/platform) decide which factories are available by including them
- * in images (`DextoImage.storage.cache`).
+ * multiple concrete backends.
  *
  * ## Usage
- * Cache 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`.
+ * Cache backends are typically constructed by an image's storage implementation after validating
+ * config with the matching schema.
  */
-export type { CacheFactory } from './factory.js';
 export type { Cache } from './types.js';
-export { inMemoryCacheFactory, redisCacheFactory } from './factories/index.js';
 export { CACHE_TYPES, CacheConfigSchema, InMemoryCacheSchema, RedisCacheSchema, type CacheType, type CacheConfig, type InMemoryCacheConfig, type RedisCacheConfig, } from './schemas.js';
 export { MemoryCacheStore } from './memory-cache-store.js';
+export { RedisStore } from './redis-store.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG/E,OAAO,EACH,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACxB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EACH,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACxB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/cache/index.js

@@ -1,4 +1,3 @@
-import { inMemoryCacheFactory, redisCacheFactory } from "./factories/index.js";
 import {
   CACHE_TYPES,
   CacheConfigSchema,
@@ -6,12 +5,12 @@ import {
   RedisCacheSchema
 } from "./schemas.js";
 import { MemoryCacheStore } from "./memory-cache-store.js";
+import { RedisStore } from "./redis-store.js";
 export {
   CACHE_TYPES,
   CacheConfigSchema,
   InMemoryCacheSchema,
   MemoryCacheStore,
   RedisCacheSchema,
-  inMemoryCacheFactory,
-  redisCacheFactory
+  RedisStore
 };

package/dist/cache/schemas.cjs

@@ -25,7 +25,7 @@ __export(schemas_exports, {
 });
 module.exports = __toCommonJS(schemas_exports);
 var import_zod = require("zod");
-var import_core = require("@dexto/core");
+var import_config = require("@dexto/core/config");
 const CACHE_TYPES = ["in-memory", "redis"];
 const BaseCacheSchema = import_zod.z.object({
   maxConnections: import_zod.z.number().int().positive().optional().describe("Maximum connections"),
@@ -39,7 +39,7 @@ const InMemoryCacheSchema = BaseCacheSchema.extend({
 }).strict();
 const RedisCacheSchema = BaseCacheSchema.extend({
   type: import_zod.z.literal("redis"),
-  url: (0, import_core.EnvExpandedString)().optional().describe("Redis connection URL (redis://...)"),
+  url: (0, import_config.EnvExpandedString)().optional().describe("Redis connection URL (redis://...)"),
   host: import_zod.z.string().optional().describe("Redis host"),
   port: import_zod.z.number().int().positive().optional().describe("Redis port"),
   password: import_zod.z.string().optional().describe("Redis password"),
@@ -51,9 +51,9 @@ const RedisCacheSchema = BaseCacheSchema.extend({
       message: "Redis cache requires either 'url' or 'host' to be specified",
       path: ["url"],
       params: {
-        code: import_core.StorageErrorCode.CONNECTION_CONFIG_MISSING,
-        scope: import_core.ErrorScope.STORAGE,
-        type: import_core.ErrorType.USER
+        code: import_config.StorageErrorCode.CONNECTION_CONFIG_MISSING,
+        scope: import_config.ErrorScope.STORAGE,
+        type: import_config.ErrorType.USER
       }
     });
   }

package/dist/cache/schemas.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { EnvExpandedString, ErrorScope, ErrorType, StorageErrorCode } from "@dexto/core";
+import { EnvExpandedString, ErrorScope, ErrorType, StorageErrorCode } from "@dexto/core/config";
 const CACHE_TYPES = ["in-memory", "redis"];
 const BaseCacheSchema = z.object({
   maxConnections: z.number().int().positive().optional().describe("Maximum connections"),

package/dist/database/index.cjs

@@ -23,15 +23,15 @@ __export(database_exports, {
   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
+  PostgresStore: () => import_postgres_store.PostgresStore,
+  SQLiteStore: () => import_sqlite_store.SQLiteStore,
+  SqliteDatabaseSchema: () => import_schemas.SqliteDatabaseSchema
 });
 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");
+var import_sqlite_store = require("./sqlite-store.js");
+var import_postgres_store = require("./postgres-store.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DATABASE_TYPES,
@@ -39,8 +39,7 @@ var import_memory_database_store = require("./memory-database-store.js");
   InMemoryDatabaseSchema,
   MemoryDatabaseStore,
   PostgresDatabaseSchema,
-  SqliteDatabaseSchema,
-  inMemoryDatabaseFactory,
-  postgresDatabaseFactory,
-  sqliteDatabaseFactory
+  PostgresStore,
+  SQLiteStore,
+  SqliteDatabaseSchema
 });

package/dist/database/index.d.ts

@@ -2,25 +2,15 @@
  * 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`).
+ * multiple concrete backends.
  *
  * ## 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`.
+ * Database backends are typically constructed by an image's storage implementation after
+ * validating config with the matching schema.
  */
-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';
+export { SQLiteStore } from './sqlite-store.js';
+export { PostgresStore } from './postgres-store.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/database/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,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;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/database/index.js

@@ -1,8 +1,3 @@
-import {
-  inMemoryDatabaseFactory,
-  sqliteDatabaseFactory,
-  postgresDatabaseFactory
-} from "./factories/index.js";
 import {
   DATABASE_TYPES,
   DatabaseConfigSchema,
@@ -11,14 +6,15 @@ import {
   PostgresDatabaseSchema
 } from "./schemas.js";
 import { MemoryDatabaseStore } from "./memory-database-store.js";
+import { SQLiteStore } from "./sqlite-store.js";
+import { PostgresStore } from "./postgres-store.js";
 export {
   DATABASE_TYPES,
   DatabaseConfigSchema,
   InMemoryDatabaseSchema,
   MemoryDatabaseStore,
   PostgresDatabaseSchema,
-  SqliteDatabaseSchema,
-  inMemoryDatabaseFactory,
-  postgresDatabaseFactory,
-  sqliteDatabaseFactory
+  PostgresStore,
+  SQLiteStore,
+  SqliteDatabaseSchema
 };

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

@@ -65,6 +65,22 @@ class MemoryDatabaseStore {
       );
     }
   }
+  async setIfAbsent(key, value) {
+    this.checkConnection();
+    try {
+      if (this.data.has(key)) {
+        return { value: this.data.get(key), inserted: false };
+      }
+      this.data.set(key, value);
+      return { value, inserted: true };
+    } catch (error) {
+      throw import_core.StorageError.writeFailed(
+        "setIfAbsent",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
   async delete(key) {
     this.checkConnection();
     this.data.delete(key);

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

@@ -14,6 +14,10 @@ export declare class MemoryDatabaseStore implements Database {
     getStoreType(): string;
     get<T>(key: string): Promise<T | undefined>;
     set<T>(key: string, value: T): Promise<void>;
+    setIfAbsent<T>(key: string, value: T): Promise<{
+        value: T;
+        inserted: boolean;
+    }>;
     delete(key: string): Promise<void>;
     list(prefix: string): Promise<string[]>;
     append<T>(key: string, item: T): Promise<void>;

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

@@ -1 +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"}
+{"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,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IAiB/E,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

@@ -42,6 +42,22 @@ class MemoryDatabaseStore {
       );
     }
   }
+  async setIfAbsent(key, value) {
+    this.checkConnection();
+    try {
+      if (this.data.has(key)) {
+        return { value: this.data.get(key), inserted: false };
+      }
+      this.data.set(key, value);
+      return { value, inserted: true };
+    } catch (error) {
+      throw StorageError.writeFailed(
+        "setIfAbsent",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
   async delete(key) {
     this.checkConnection();
     this.data.delete(key);

package/dist/database/postgres-store.cjs

@@ -163,6 +163,31 @@ class PostgresStore {
       );
     }
   }
+  async setIfAbsent(key, value) {
+    try {
+      return await this.withRetry("setIfAbsent", async (client) => {
+        const jsonValue = JSON.stringify(value);
+        const inserted = await client.query(
+          "INSERT INTO kv (key, value, updated_at) VALUES ($1, $2::jsonb, $3) ON CONFLICT (key) DO NOTHING RETURNING value",
+          [key, jsonValue, /* @__PURE__ */ new Date()]
+        );
+        if (inserted.rows[0]) {
+          return { value: inserted.rows[0].value, inserted: true };
+        }
+        const existing = await client.query("SELECT value FROM kv WHERE key = $1", [key]);
+        return {
+          value: existing.rows[0] ? existing.rows[0].value : value,
+          inserted: false
+        };
+      });
+    } catch (error) {
+      throw import_core.StorageError.writeFailed(
+        "setIfAbsent",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
   async delete(key) {
     await this.withRetry("delete", async (client) => {
       await client.query("BEGIN");

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

@@ -23,6 +23,10 @@ export declare class PostgresStore implements Database {
     getStoreType(): string;
     get<T>(key: string): Promise<T | undefined>;
     set<T>(key: string, value: T): Promise<void>;
+    setIfAbsent<T>(key: string, value: T): Promise<{
+        value: T;
+        inserted: boolean;
+    }>;
     delete(key: string): Promise<void>;
     list(prefix: string): Promise<string[]>;
     append<T>(key: string, item: T): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../../src/database/postgres-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,UAAU,EAAE,MAAM,IAAI,CAAC;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAMtC,OAAO,CAAC,MAAM;IALlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;gBAGX,MAAM,EAAE,sBAAsB,EACtC,MAAM,EAAE,MAAM;IAKZ,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+F9B;;OAEG;YACW,YAAY;IAmBpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,MAAM;IAKhB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAe3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmBvC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;YAW5D,YAAY;IA4B1B,OAAO,CAAC,eAAe;IAMvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;OAGG;YACW,SAAS;IA8CvB;;;;OAIG;IACG,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAcxE,QAAQ,IAAI,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAC;IAkBI,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}
+{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../../src/database/postgres-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,UAAU,EAAE,MAAM,IAAI,CAAC;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAMtC,OAAO,CAAC,MAAM;IALlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;gBAGX,MAAM,EAAE,sBAAsB,EACtC,MAAM,EAAE,MAAM;IAKZ,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+F9B;;OAEG;YACW,YAAY;IAmBpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,MAAM;IAKhB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAe3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB5C,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IA2B/E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmBvC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;YAW5D,YAAY;IA4B1B,OAAO,CAAC,eAAe;IAMvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;OAGG;YACW,SAAS;IA8CvB;;;;OAIG;IACG,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAcxE,QAAQ,IAAI,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAC;IAkBI,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}

package/dist/database/postgres-store.js

@@ -140,6 +140,31 @@ class PostgresStore {
       );
     }
   }
+  async setIfAbsent(key, value) {
+    try {
+      return await this.withRetry("setIfAbsent", async (client) => {
+        const jsonValue = JSON.stringify(value);
+        const inserted = await client.query(
+          "INSERT INTO kv (key, value, updated_at) VALUES ($1, $2::jsonb, $3) ON CONFLICT (key) DO NOTHING RETURNING value",
+          [key, jsonValue, /* @__PURE__ */ new Date()]
+        );
+        if (inserted.rows[0]) {
+          return { value: inserted.rows[0].value, inserted: true };
+        }
+        const existing = await client.query("SELECT value FROM kv WHERE key = $1", [key]);
+        return {
+          value: existing.rows[0] ? existing.rows[0].value : value,
+          inserted: false
+        };
+      });
+    } catch (error) {
+      throw StorageError.writeFailed(
+        "setIfAbsent",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
   async delete(key) {
     await this.withRetry("delete", async (client) => {
       await client.query("BEGIN");

package/dist/database/schemas.cjs

@@ -26,7 +26,7 @@ __export(schemas_exports, {
 });
 module.exports = __toCommonJS(schemas_exports);
 var import_zod = require("zod");
-var import_core = require("@dexto/core");
+var import_config = require("@dexto/core/config");
 const DATABASE_TYPES = ["in-memory", "sqlite", "postgres"];
 const BaseDatabaseSchema = import_zod.z.object({
   maxConnections: import_zod.z.number().int().positive().optional().describe("Maximum connections"),
@@ -46,8 +46,8 @@ const SqliteDatabaseSchema = BaseDatabaseSchema.extend({
 }).strict();
 const PostgresDatabaseSchema = BaseDatabaseSchema.extend({
   type: import_zod.z.literal("postgres"),
-  url: (0, import_core.EnvExpandedString)().optional().describe("PostgreSQL connection URL (postgresql://...)"),
-  connectionString: (0, import_core.EnvExpandedString)().optional().describe("PostgreSQL connection string"),
+  url: (0, import_config.EnvExpandedString)().optional().describe("PostgreSQL connection URL (postgresql://...)"),
+  connectionString: (0, import_config.EnvExpandedString)().optional().describe("PostgreSQL connection string"),
   host: import_zod.z.string().optional().describe("PostgreSQL host"),
   port: import_zod.z.number().int().positive().optional().describe("PostgreSQL port"),
   database: import_zod.z.string().optional().describe("PostgreSQL database name"),
@@ -62,9 +62,9 @@ const PostgresDatabaseSchema = BaseDatabaseSchema.extend({
       message: "PostgreSQL database requires one of 'url', 'connectionString', or 'host' to be specified",
       path: ["url"],
       params: {
-        code: import_core.StorageErrorCode.CONNECTION_CONFIG_MISSING,
-        scope: import_core.ErrorScope.STORAGE,
-        type: import_core.ErrorType.USER
+        code: import_config.StorageErrorCode.CONNECTION_CONFIG_MISSING,
+        scope: import_config.ErrorScope.STORAGE,
+        type: import_config.ErrorType.USER
       }
     });
   }

package/dist/database/schemas.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { EnvExpandedString, ErrorScope, ErrorType, StorageErrorCode } from "@dexto/core";
+import { EnvExpandedString, ErrorScope, ErrorType, StorageErrorCode } from "@dexto/core/config";
 const DATABASE_TYPES = ["in-memory", "sqlite", "postgres"];
 const BaseDatabaseSchema = z.object({
   maxConnections: z.number().int().positive().optional().describe("Maximum connections"),

package/dist/database/sqlite-store.cjs

@@ -177,6 +177,24 @@ class SQLiteStore {
       );
     }
   }
+  async setIfAbsent(key, value) {
+    this.checkConnection();
+    try {
+      const serialized = JSON.stringify(value);
+      const result = this.db.prepare("INSERT OR IGNORE INTO kv_store (key, value, updated_at) VALUES (?, ?, ?)").run(key, serialized, Date.now());
+      const row = this.db.prepare("SELECT value FROM kv_store WHERE key = ?").get(key);
+      return {
+        value: row ? JSON.parse(row.value) : value,
+        inserted: result.changes > 0
+      };
+    } catch (error) {
+      throw import_core.StorageError.writeFailed(
+        "setIfAbsent",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
   async delete(key) {
     this.checkConnection();
     try {

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

@@ -18,6 +18,10 @@ export declare class SQLiteStore implements Database {
     getStoreType(): string;
     get<T>(key: string): Promise<T | undefined>;
     set<T>(key: string, value: T): Promise<void>;
+    setIfAbsent<T>(key: string, value: T): Promise<{
+        value: T;
+        inserted: boolean;
+    }>;
     delete(key: string): Promise<void>;
     list(prefix: string): Promise<string[]>;
     append<T>(key: string, item: T): Promise<void>;