@fragno-dev/db 0.2.2 → 0.3.0

package/src/adapters/shared/from-unit-of-work-compiler.ts

@@ -5,6 +5,7 @@ import type {
   UOWCompiler,
   UOWDecoder,
   UOWExecutor,
+  UOWInstrumentation,
   ValidIndexName,
 } from "../../query/unit-of-work/unit-of-work";
 import { UnitOfWork } from "../../query/unit-of-work/unit-of-work";
@@ -25,6 +26,7 @@ export interface UnitOfWorkConfig {
    * since those have to be manually executed.
    */
   dryRun?: boolean;
+  instrumentation?: UOWInstrumentation;
 }
 
 /**
@@ -50,7 +52,7 @@ export interface UnitOfWorkFactory {
   /**
    * Optional WeakMap for schema-to-namespace lookups
    */
-  schemaNamespaceMap?: WeakMap<AnySchema, string>;
+  schemaNamespaceMap?: WeakMap<AnySchema, string | null>;
 }
 
 /**

package/src/adapters/shared/uow-operation-compiler.ts

@@ -8,7 +8,7 @@ import type {
 } from "../../query/unit-of-work/unit-of-work";
 import { Cursor } from "../../query/cursor";
 import type { DriverConfig } from "../generic-sql/driver-config";
-import { createTableNameMapper, type TableNameMapper } from "./table-name-mapper";
+import { createNamingResolver, type NamingResolver } from "../../naming/sql-naming";
 
 /**
  * Options for compiling a find operation with cursor pagination
@@ -55,24 +55,24 @@ export interface CursorConditionResult {
  */
 export abstract class UOWOperationCompiler<TCompiledQuery> {
   #driverConfig: DriverConfig;
-  #mapperFactory?: (namespace: string | undefined) => TableNameMapper | undefined;
+  #resolverFactory?: (schema: AnySchema, namespace: string | null) => NamingResolver;
 
   constructor(
     driverConfig: DriverConfig,
-    mapperFactory?: (namespace: string | undefined) => TableNameMapper | undefined,
+    resolverFactory?: (schema: AnySchema, namespace: string | null) => NamingResolver,
   ) {
     this.#driverConfig = driverConfig;
-    this.#mapperFactory = mapperFactory;
+    this.#resolverFactory = resolverFactory;
   }
 
   protected get driverConfig(): DriverConfig {
     return this.#driverConfig;
   }
 
-  protected get mapperFactory():
-    | ((namespace: string | undefined) => TableNameMapper | undefined)
+  protected get resolverFactory():
+    | ((schema: AnySchema, namespace: string | null) => NamingResolver)
     | undefined {
-    return this.#mapperFactory;
+    return this.#resolverFactory;
   }
 
   abstract compileCount(
@@ -105,12 +105,18 @@ export abstract class UOWOperationCompiler<TCompiledQuery> {
   /**
    * Get the mapper for a specific operation based on its namespace
    */
-  protected getMapperForOperation(namespace: string | undefined): TableNameMapper | undefined {
-    return this.#mapperFactory
-      ? this.#mapperFactory(namespace)
-      : namespace
-        ? createTableNameMapper(namespace)
-        : undefined;
+  protected getNamingResolver(
+    schema: AnySchema,
+    namespace: string | null | undefined,
+  ): NamingResolver {
+    if (this.#resolverFactory) {
+      return this.#resolverFactory(schema, namespace ?? null);
+    }
+    return createNamingResolver(
+      schema,
+      namespace ?? null,
+      this.#driverConfig.defaultNamingStrategy,
+    );
   }
 
   /**
@@ -154,9 +160,13 @@ export abstract class UOWOperationCompiler<TCompiledQuery> {
   /**
    * Get the physical table name for an operation, applying namespace mapping if needed
    */
-  protected getPhysicalTableName(logicalName: string, namespace: string | undefined): string {
-    const mapper = this.getMapperForOperation(namespace);
-    return mapper ? mapper.toPhysical(logicalName) : logicalName;
+  protected getPhysicalTableName(
+    schema: AnySchema,
+    logicalName: string,
+    namespace: string | undefined,
+  ): string {
+    const resolver = this.getNamingResolver(schema, namespace ?? null);
+    return resolver.getTableName(logicalName);
   }
 }
 

package/src/adapters/sql/index.ts

@@ -0,0 +1,12 @@
+export {
+  SqlAdapter,
+  type SqlAdapterOptions,
+  type UnitOfWorkConfig,
+  type OutboxConfig,
+  sqliteProfiles,
+  sqliteStorageDefault,
+  sqliteStoragePrisma,
+  type SQLiteStorageMode,
+} from "../generic-sql/generic-sql-adapter";
+
+export type { SQLiteProfile } from "../adapters";

package/src/db-fragment-definition-builder.test.ts

@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { describe, it, expect, vi, expectTypeOf } from "vitest";
 import { defineFragment } from "@fragno-dev/core";
 import {
@@ -9,9 +12,11 @@ import { schema, column, idColumn } from "./schema/create";
 import type { SimpleQueryInterface } from "./query/simple-query-interface";
 import type { DatabaseAdapter } from "./adapters/adapters";
 import * as executeUnitOfWork from "./query/unit-of-work/execute-unit-of-work";
+import { RequestContextStorage } from "@fragno-dev/core/internal/request-context-storage";
+import { suffixNamingStrategy } from "./naming/sql-naming";
 
 // Create a test schema
-const testSchema = schema((s) => {
+const testSchema = schema("test", (s) => {
   return s.addTable("users", (t) => {
     return t
       .addColumn("id", idColumn())
@@ -29,13 +34,17 @@ function createMockAdapter(): DatabaseAdapter {
       forSchema: vi.fn(),
       executeRetrieve: vi.fn(),
       executeMutations: vi.fn(),
+      registerSchema: vi.fn(),
+      reset: vi.fn(),
     })),
   } as unknown as SimpleQueryInterface<TestSchema>;
 
   return {
     createQueryEngine: vi.fn(() => mockdb),
-    migrate: vi.fn(),
+    getSchemaVersion: vi.fn(async () => undefined),
     close: vi.fn(),
+    contextStorage: new RequestContextStorage(),
+    namingStrategy: suffixNamingStrategy,
   } as unknown as DatabaseAdapter;
 }
 
@@ -735,10 +744,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
 
       const mockAdapter = createMockAdapter();
 
-      const definition = withDatabase(
-        testSchema,
-        "my-namespace",
-      )(defineFragment<Config>("complex-db-frag"))
+      const definition = withDatabase(testSchema)(defineFragment<Config>("complex-db-frag"))
         .withDependencies(({ config }) => ({
           connectionString: config.dbConnectionString,
           debug: config.debug,
@@ -806,17 +812,29 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
     });
   });
 
-  describe("error handling", () => {
-    it("should throw error if database adapter is missing", () => {
+  describe("default adapter", () => {
+    it("should default to sqlite adapter when database adapter is missing", () => {
+      const previous = process.env["FRAGNO_DATA_DIR"];
+      const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "fragno-db-default-"));
+      process.env["FRAGNO_DATA_DIR"] = dataDir;
+
       const definition = withDatabase(testSchema)(defineFragment("db-frag")).build();
 
-      expect(() => {
-        definition.dependencies!({
+      try {
+        const deps = definition.dependencies!({
           config: {},
-          // @ts-expect-error No databaseAdapter - intentionally invalid for runtime error test
           options: {},
         });
-      }).toThrow("Database fragment requires a database adapter");
+
+        expect(deps.db).toBeDefined();
+        expect(deps.createUnitOfWork).toBeDefined();
+      } finally {
+        if (previous === undefined) {
+          delete process.env["FRAGNO_DATA_DIR"];
+        } else {
+          process.env["FRAGNO_DATA_DIR"] = previous;
+        }
+      }
     });
   });
 

package/src/db-fragment-definition-builder.ts

@@ -21,20 +21,34 @@ import {
 } from "./query/unit-of-work/execute-unit-of-work";
 import {
   prepareHookMutations,
-  processHooks,
   type HooksMap,
   type HookFn,
   type HookContext,
+  type HookProcessorConfig,
+  type DurableHooksProcessingOptions,
+  createHookScheduler,
 } from "./hooks/hooks";
 import type { InternalFragmentInstance } from "./fragments/internal-fragment";
+import { resolveDatabaseAdapter } from "./util/default-database-adapter";
+import { sanitizeNamespace } from "./naming/sql-naming";
 
 /**
- * Extended FragnoPublicConfig that includes a database adapter.
- * Use this type when creating fragments with database support.
+ * Extended FragnoPublicConfig for database fragments.
+ * If databaseAdapter is omitted and better-sqlite3 is available, a default SQLite adapter is used.
  */
 export type FragnoPublicConfigWithDatabase = FragnoPublicConfig & {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  databaseAdapter: DatabaseAdapter<any>;
+  databaseAdapter?: DatabaseAdapter<any>;
+  /**
+   * Optional durable hooks processing configuration.
+   */
+  durableHooks?: DurableHooksProcessingOptions;
+  /**
+   * Optional override for database namespace. If provided (including null), it is used as-is
+   * without sanitization — the caller is responsible for providing a valid namespace.
+   * When omitted, defaults to a sanitized version of schema.name.
+   */
+  databaseNamespace?: string | null;
 };
 
 /**
@@ -44,6 +58,7 @@ export type FragnoPublicConfigWithDatabase = FragnoPublicConfig & {
 export type ImplicitDatabaseDependencies<TSchema extends AnySchema> = {
   /**
    * Database query engine for the fragment's schema.
+   * @deprecated Prefer handlerTx/serviceTx instead of direct db usage.
    */
   db: SimpleQueryInterface<TSchema>;
   /**
@@ -53,7 +68,7 @@ export type ImplicitDatabaseDependencies<TSchema extends AnySchema> = {
   /**
    * The database namespace for this fragment.
    */
-  namespace: string;
+  namespace: string | null;
   /**
    * Create a new Unit of Work for database operations.
    */
@@ -145,21 +160,23 @@ export type DatabaseFragmentContext<TSchema extends AnySchema> = {
 function createDatabaseContext<TSchema extends AnySchema>(
   options: FragnoPublicConfigWithDatabase,
   schema: TSchema,
-  namespace: string,
 ): DatabaseFragmentContext<TSchema> {
-  const databaseAdapter = options.databaseAdapter;
-
-  if (!databaseAdapter) {
-    throw new Error(
-      "Database fragment requires a database adapter to be provided in options.databaseAdapter",
-    );
-  }
+  const databaseAdapter = resolveDatabaseAdapter(options, schema);
 
+  const namespace = resolveDatabaseNamespace(options, schema);
   const db = databaseAdapter.createQueryEngine(schema, namespace);
 
   return { databaseAdapter, db };
 }
 
+function resolveDatabaseNamespace<TSchema extends AnySchema>(
+  options: FragnoPublicConfigWithDatabase,
+  schema: TSchema,
+): string | null {
+  const hasOverride = options.databaseNamespace !== undefined;
+  return hasOverride ? (options.databaseNamespace ?? null) : sanitizeNamespace(schema.name);
+}
+
 /**
  * Storage type for database fragments - stores the Unit of Work.
  */
@@ -171,7 +188,7 @@ export type DatabaseRequestStorage = {
  * Builder for database fragments that wraps the core fragment builder
  * and provides database-specific functionality.
  *
- * Database fragments always require FragnoPublicConfigWithDatabase (which includes databaseAdapter).
+ * Database fragments use FragnoPublicConfigWithDatabase and default the adapter when possible.
  */
 export class DatabaseFragmentDefinitionBuilder<
   TSchema extends AnySchema,
@@ -201,7 +218,6 @@ export class DatabaseFragmentDefinitionBuilder<
     TLinkedFragments
   >;
   #schema: TSchema;
-  #namespace: string;
   #hooksFactory?: (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => THooks;
 
   constructor(
@@ -219,7 +235,6 @@ export class DatabaseFragmentDefinitionBuilder<
       TLinkedFragments
     >,
     schema: TSchema,
-    namespace?: string,
     hooksFactory?: (context: {
       config: TConfig;
       options: FragnoPublicConfigWithDatabase;
@@ -227,7 +242,6 @@ export class DatabaseFragmentDefinitionBuilder<
   ) {
     this.#baseBuilder = baseBuilder;
     this.#schema = schema;
-    this.#namespace = namespace ?? baseBuilder.name;
     this.#hooksFactory = hooksFactory;
   }
 
@@ -257,7 +271,8 @@ export class DatabaseFragmentDefinitionBuilder<
   > {
     // Wrap user function to inject DB context
     const wrappedFn = (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => {
-      const dbContext = createDatabaseContext(context.options, this.#schema, this.#namespace);
+      const dbContext = createDatabaseContext(context.options, this.#schema);
+      const namespace = resolveDatabaseNamespace(context.options, this.#schema);
 
       // Call user function with enriched context
       const userDeps = fn({
@@ -272,7 +287,7 @@ export class DatabaseFragmentDefinitionBuilder<
       const implicitDeps: ImplicitDatabaseDependencies<TSchema> = {
         db: dbContext.db,
         schema: this.#schema,
-        namespace: this.#namespace,
+        namespace,
         createUnitOfWork: createUow,
       };
 
@@ -285,12 +300,7 @@ export class DatabaseFragmentDefinitionBuilder<
     // Create new base builder with wrapped function
     const newBaseBuilder = this.#baseBuilder.withDependencies(wrappedFn);
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   providesBaseService<TNewService>(
@@ -318,12 +328,7 @@ export class DatabaseFragmentDefinitionBuilder<
   > {
     const newBaseBuilder = this.#baseBuilder.providesBaseService<TNewService>(fn);
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   providesService<TServiceName extends string, TService>(
@@ -355,12 +360,7 @@ export class DatabaseFragmentDefinitionBuilder<
       fn,
     );
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   /**
@@ -399,12 +399,7 @@ export class DatabaseFragmentDefinitionBuilder<
       fn,
     );
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   /**
@@ -468,7 +463,6 @@ export class DatabaseFragmentDefinitionBuilder<
     const newBuilder = new DatabaseFragmentDefinitionBuilder(
       this.#baseBuilder,
       this.#schema,
-      this.#namespace,
     ) as unknown as DatabaseFragmentDefinitionBuilder<
       TSchema,
       TConfig,
@@ -509,12 +503,7 @@ export class DatabaseFragmentDefinitionBuilder<
   > {
     const newBaseBuilder = this.#baseBuilder.usesService<TServiceName, TService>(serviceName);
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   /**
@@ -540,12 +529,7 @@ export class DatabaseFragmentDefinitionBuilder<
       serviceName,
     );
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   /**
@@ -594,12 +578,13 @@ export class DatabaseFragmentDefinitionBuilder<
         }
       }
 
-      const { db } = createDatabaseContext(context.options, this.#schema, this.#namespace);
+      const { db } = createDatabaseContext(context.options, this.#schema);
+      const namespace = resolveDatabaseNamespace(context.options, this.#schema);
 
       const implicitDeps: ImplicitDatabaseDependencies<TSchema> = {
         db,
         schema: this.#schema,
-        namespace: this.#namespace,
+        namespace,
         createUnitOfWork: () => db.createUnitOfWork(),
       };
 
@@ -612,7 +597,7 @@ export class DatabaseFragmentDefinitionBuilder<
     // Use the adapter's shared context storage (all fragments using the same adapter share this storage)
     const builderWithExternalStorage = this.#baseBuilder.withExternalRequestStorage(
       ({ options }) => {
-        const dbContext = createDatabaseContext(options, this.#schema, this.#namespace);
+        const dbContext = createDatabaseContext(options, this.#schema);
         return dbContext.databaseAdapter.contextStorage;
       },
     );
@@ -621,7 +606,7 @@ export class DatabaseFragmentDefinitionBuilder<
     const builderWithStorage = builderWithExternalStorage.withRequestStorage(
       ({ options }): DatabaseRequestStorage => {
         // Create database context - needed here to create the UOW
-        const dbContextForStorage = createDatabaseContext(options, this.#schema, this.#namespace);
+        const dbContextForStorage = createDatabaseContext(options, this.#schema);
 
         // Create a new Unit of Work for this request
         const uow: IUnitOfWork = dbContextForStorage.db.createUnitOfWork();
@@ -637,18 +622,91 @@ export class DatabaseFragmentDefinitionBuilder<
       options: FragnoPublicConfigWithDatabase;
     }) => InternalFragmentInstance;
 
+    // Cache per instantiated fragment (deps object is unique per instantiation).
+    const hooksConfigCache = new WeakMap<object, HookProcessorConfig<THooks>>();
+
+    const createHooksConfig = (context: {
+      config: TConfig;
+      options: FragnoPublicConfigWithDatabase;
+      deps: TDeps;
+    }) => {
+      if (!this.#hooksFactory) {
+        return undefined;
+      }
+      const depsKey =
+        typeof context.deps === "object" && context.deps !== null
+          ? (context.deps as object)
+          : undefined;
+      const cachedHooksConfig = depsKey ? hooksConfigCache.get(depsKey) : undefined;
+      if (cachedHooksConfig) {
+        return cachedHooksConfig;
+      }
+
+      const namespace = resolveDatabaseNamespace(context.options, this.#schema);
+      const namespaceKey = namespace ?? this.#schema.name;
+      const durableHooksOptions = context.options.durableHooks;
+      const baseAdapter = resolveDatabaseAdapter(context.options, this.#schema);
+      const hookAdapter = baseAdapter.getHookProcessingAdapter?.() ?? baseAdapter;
+      const hookOptions =
+        hookAdapter === baseAdapter
+          ? context.options
+          : { ...context.options, databaseAdapter: hookAdapter };
+      const dbContextForHooks = createDatabaseContext(hookOptions, this.#schema);
+      const hooksConfig: HookProcessorConfig<THooks> = {
+        hooks: this.#hooksFactory(context),
+        namespace: namespaceKey,
+        internalFragment: internalFragmentFactory({
+          config: context.config,
+          options: hookOptions,
+        }),
+        handlerTx: (execOptions?: Omit<ExecuteTxOptions, "createUnitOfWork">) => {
+          const userOnBeforeMutate = execOptions?.onBeforeMutate;
+          const userOnAfterMutate = execOptions?.onAfterMutate;
+          return createHandlerTxBuilder<THooks>({
+            ...execOptions,
+            createUnitOfWork: () => {
+              const uow = dbContextForHooks.db.createUnitOfWork();
+              uow.registerSchema(
+                hooksConfig.internalFragment.$internal.deps.schema,
+                hooksConfig.internalFragment.$internal.deps.namespace,
+              );
+              return uow;
+            },
+            onBeforeMutate: (uow) => {
+              prepareHookMutations(uow, hooksConfig);
+              if (userOnBeforeMutate) {
+                userOnBeforeMutate(uow);
+              }
+            },
+            onAfterMutate: async (uow) => {
+              void hooksConfig.scheduler?.schedule().catch((error) => {
+                console.error("Durable hooks processing failed", error);
+              });
+              if (userOnAfterMutate) {
+                await userOnAfterMutate(uow);
+              }
+            },
+          });
+        },
+        stuckProcessingTimeoutMinutes: durableHooksOptions?.stuckProcessingTimeoutMinutes,
+        onStuckProcessingHooks: durableHooksOptions?.onStuckProcessingHooks,
+      };
+      hooksConfig.scheduler = createHookScheduler(hooksConfig);
+      if (depsKey) {
+        hooksConfigCache.set(depsKey, hooksConfig);
+      }
+      return hooksConfig;
+    };
+
     const builderWithContext = builderWithStorage.withThisContext<
       DatabaseServiceContext<THooks>,
       DatabaseHandlerContext<THooks>
-    >(({ storage, config, options }) => {
+    >(({ storage, config, options, deps }) => {
       // Create hooks config if hooks factory is defined
-      const hooksConfig = this.#hooksFactory
-        ? {
-            hooks: this.#hooksFactory({ config, options }),
-            namespace: this.#namespace,
-            internalFragment: internalFragmentFactory({ config, options }),
-          }
-        : undefined;
+      const hooksConfig = createHooksConfig({ config, options, deps });
+      const internalFragment =
+        hooksConfig?.internalFragment ??
+        (internalFragmentFactory ? internalFragmentFactory({ config, options }) : undefined);
 
       // Builder API: serviceTx using createServiceTxBuilder
       function serviceTx<TSchema extends AnySchema>(schema: TSchema) {
@@ -681,10 +739,10 @@ export class DatabaseFragmentDefinitionBuilder<
           ...execOptions,
           createUnitOfWork: () => {
             currentStorage.uow.reset();
-            if (hooksConfig) {
+            if (internalFragment) {
               currentStorage.uow.registerSchema(
-                hooksConfig.internalFragment.$internal.deps.schema,
-                hooksConfig.internalFragment.$internal.deps.namespace,
+                internalFragment.$internal.deps.schema,
+                internalFragment.$internal.deps.namespace,
               );
             }
             return currentStorage.uow;
@@ -698,8 +756,10 @@ export class DatabaseFragmentDefinitionBuilder<
             }
           },
           onAfterMutate: async (uow) => {
-            if (hooksConfig) {
-              await processHooks(hooksConfig);
+            if (hooksConfig?.scheduler) {
+              void hooksConfig.scheduler.schedule().catch((error) => {
+                console.error("Durable hooks processing failed", error);
+              });
             }
             if (userOnAfterMutate) {
               await userOnAfterMutate(uow);
@@ -717,6 +777,15 @@ export class DatabaseFragmentDefinitionBuilder<
 
     // Build the final definition
     const finalDef = builderWithContext.build();
+    if (this.#hooksFactory) {
+      finalDef.internalDataFactory = ({ config, options, deps }) => ({
+        durableHooks: createHooksConfig({
+          config: config as TConfig,
+          options: options as FragnoPublicConfigWithDatabase,
+          deps: deps as TDeps,
+        }),
+      });
+    }
 
     // Return the complete definition with proper typing and dependencies
     return {