@fragno-dev/db 0.2.1 → 0.2.2

package/dist/db-fragment-definition-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"db-fragment-definition-builder.js","names":["#baseBuilder","#schema","#namespace","#hooksFactory","implicitDeps: ImplicitDatabaseDependencies<TSchema>","uow","serviceContext: DatabaseServiceContext<THooks>","options: ExecuteRestrictedUnitOfWorkOptions","options"],"sources":["../src/db-fragment-definition-builder.ts"],"sourcesContent":["import type { AnySchema } from \"./schema/create\";\nimport type { SimpleQueryInterface } from \"./query/simple-query-interface\";\nimport type { DatabaseAdapter } from \"./adapters/adapters\";\nimport type { IUnitOfWork } from \"./query/unit-of-work/unit-of-work\";\nimport { TypedUnitOfWork, UnitOfWork } from \"./query/unit-of-work/unit-of-work\";\nimport type {\n  RequestThisContext,\n  FragnoPublicConfig,\n  AnyFragnoInstantiatedFragment,\n} from \"@fragno-dev/core\";\nimport {\n  FragmentDefinitionBuilder,\n  type FragmentDefinition,\n  type ServiceConstructorFn,\n} from \"@fragno-dev/core\";\nimport {\n  executeRestrictedUnitOfWork,\n  executeTxArray,\n  executeTxCallbacks,\n  executeServiceTx,\n  type AwaitedPromisesInObject,\n  type ExecuteRestrictedUnitOfWorkOptions,\n  type HandlerTxCallbacks,\n  type ServiceTxCallbacks,\n} from \"./query/unit-of-work/execute-unit-of-work\";\nimport {\n  prepareHookMutations,\n  processHooks,\n  type HooksMap,\n  type HookFn,\n  type HookContext,\n} from \"./hooks/hooks\";\nimport type { InternalFragmentInstance } from \"./fragments/internal-fragment\";\n\n/**\n * Extended FragnoPublicConfig that includes a database adapter.\n * Use this type when creating fragments with database support.\n */\nexport type FragnoPublicConfigWithDatabase = FragnoPublicConfig & {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  databaseAdapter: DatabaseAdapter<any>;\n};\n\n/**\n * Implicit dependencies that database fragments get automatically.\n * These are injected without requiring explicit configuration.\n */\nexport type ImplicitDatabaseDependencies<TSchema extends AnySchema> = {\n  /**\n   * Database query engine for the fragment's schema.\n   */\n  db: SimpleQueryInterface<TSchema>;\n  /**\n   * The schema definition for this fragment.\n   */\n  schema: TSchema;\n  /**\n   * The database namespace for this fragment.\n   */\n  namespace: string;\n  /**\n   * Create a new Unit of Work for database operations.\n   */\n  createUnitOfWork: () => IUnitOfWork;\n};\n\n/**\n * Service context for database fragments - provides restricted UOW access without execute methods.\n */\nexport type DatabaseServiceContext<THooks extends HooksMap> = RequestThisContext & {\n  /**\n   * Get a typed, restricted Unit of Work for the given schema.\n   * @param schema - Schema to get a typed view for\n   * @returns TypedUnitOfWork (restricted version without execute methods)\n   */\n  uow<TSchema extends AnySchema>(schema: TSchema): TypedUnitOfWork<TSchema, [], unknown, THooks>;\n\n  /**\n   * Execute a transaction with two-phase callbacks (retrieve + mutate).\n   *\n   * @param schema - Schema to use for the transaction\n   * @param callbacks - Object containing retrieve and mutate callbacks\n   * @returns Promise resolving to the mutation result with promises awaited 1 level deep\n   *\n   * @example\n   * ```ts\n   * return this.tx(schema, {\n   *   retrieve: (uow) => uow.findFirst(\"users\", ...),\n   *   mutate: async (uow, [user]) => {\n   *     await validateUser(user);\n   *     uow.update(\"users\", user.id, ...).check();\n   *     return { ok: true };\n   *   }\n   * });\n   * ```\n   */\n  tx<TSchema extends AnySchema, TRetrievalResults extends unknown[], TMutationResult = void>(\n    schema: TSchema,\n    callbacks: ServiceTxCallbacks<TSchema, TRetrievalResults, TMutationResult, THooks>,\n  ): Promise<AwaitedPromisesInObject<TMutationResult>>;\n};\n\n/**\n * Handler context for database fragments - provides UOW execution with automatic retry support.\n */\nexport type DatabaseHandlerContext<THooks extends HooksMap = {}> = RequestThisContext & {\n  /**\n   * Execute a Unit of Work with explicit phase control and automatic retry support.\n   * This method provides an API where users call forSchema to create a schema-specific\n   * UOW, then call executeRetrieve() and executeMutate() to execute the phases. The entire\n   * callback is re-executed on optimistic concurrency conflicts, ensuring retries work properly.\n   * Automatically provides the UOW factory from context.\n   * Promises in the returned object are awaited 1 level deep.\n   *\n   * @param callback - Async function that receives a context with forSchema, executeRetrieve, executeMutate, nonce, and currentAttempt\n   * @param options - Optional configuration for retry policy and abort signal\n   * @returns Promise resolving to the callback's return value with promises awaited 1 level deep\n   * @throws Error if retries are exhausted or callback throws an error\n   *\n   * @example\n   * ```ts\n   * const result = await this.uow(async ({ forSchema, executeRetrieve, executeMutate, nonce, currentAttempt }) => {\n   *   const uow = forSchema(schema);\n   *   const userId = uow.create(\"users\", { name: \"John\" });\n   *\n   *   // Execute retrieval phase\n   *   await executeRetrieve();\n   *\n   *   const profileId = uow.create(\"profiles\", { userId });\n   *\n   *   // Execute mutation phase\n   *   await executeMutate();\n   *\n   *   return { userId, profileId };\n   * });\n   * ```\n   */\n  uow<TResult>(\n    callback: (context: {\n      forSchema: <TSchema extends AnySchema, H extends HooksMap = THooks>(\n        schema: TSchema,\n        hooks?: H,\n      ) => TypedUnitOfWork<TSchema, [], unknown, H>;\n      executeRetrieve: () => Promise<void>;\n      executeMutate: () => Promise<void>;\n      nonce: string;\n      currentAttempt: number;\n    }) => Promise<TResult> | TResult,\n    options?: Omit<ExecuteRestrictedUnitOfWorkOptions, \"createUnitOfWork\">,\n  ): Promise<AwaitedPromisesInObject<TResult>>;\n\n  /**\n   * Execute a transaction with automatic retry support.\n   * Provides two overloads: array syntax (common case) and callback syntax (advanced).\n   *\n   * Array syntax - pass a factory function that returns service calls:\n   * ```ts\n   * const [transfer, notify] = await this.tx(\n   *   () => [\n   *     services.transfer({ from, to, amount }),\n   *     services.notify({ userId, message })\n   *   ]\n   * );\n   * ```\n   *\n   * Callback syntax - for handlers that need direct UOW access:\n   * ```ts\n   * const result = await this.tx({\n   *   retrieve: ({ forSchema }) => {\n   *     const uow = forSchema(schema);\n   *     uow.find(\"users\", ...);\n   *     return services.transfer({ ... });\n   *   },\n   *   mutate: ({ forSchema }, transferPromise) => {\n   *     const uow = forSchema(schema);\n   *     uow.create(\"auditLog\", { ... });\n   *     return transferPromise;\n   *   }\n   * });\n   * ```\n   *\n   * Note: Handler callbacks are synchronous only to prevent accidentally awaiting services in wrong place.\n   */\n  // Overload 1: Array syntax (common case) - accepts a factory\n  tx<T extends readonly unknown[]>(\n    servicesFactory: () => readonly [...{ [K in keyof T]: Promise<T[K]> }],\n    options?: Omit<ExecuteRestrictedUnitOfWorkOptions, \"createUnitOfWork\">,\n  ): Promise<{ [K in keyof T]: T[K] }>;\n  // Overload 2: Callback syntax (advanced, sync callbacks only)\n  tx<TRetrieveResult, TMutationResult>(\n    callbacks: HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks>,\n    options?: Omit<ExecuteRestrictedUnitOfWorkOptions, \"createUnitOfWork\">,\n  ): Promise<AwaitedPromisesInObject<TMutationResult>>;\n};\n\n/**\n * Database fragment context provided to user callbacks.\n */\nexport type DatabaseFragmentContext<TSchema extends AnySchema> = {\n  /**\n   * Database adapter instance.\n   */\n  databaseAdapter: DatabaseAdapter<any>; // eslint-disable-line @typescript-eslint/no-explicit-any\n  /**\n   * ORM query engine for the fragment's schema.\n   */\n  db: SimpleQueryInterface<TSchema>;\n};\n\n/**\n * Create database context from options.\n * This extracts the database adapter and creates the ORM instance.\n */\nfunction createDatabaseContext<TSchema extends AnySchema>(\n  options: FragnoPublicConfigWithDatabase,\n  schema: TSchema,\n  namespace: string,\n): DatabaseFragmentContext<TSchema> {\n  const databaseAdapter = options.databaseAdapter;\n\n  if (!databaseAdapter) {\n    throw new Error(\n      \"Database fragment requires a database adapter to be provided in options.databaseAdapter\",\n    );\n  }\n\n  const db = databaseAdapter.createQueryEngine(schema, namespace);\n\n  return { databaseAdapter, db };\n}\n\n/**\n * Storage type for database fragments - stores the Unit of Work.\n */\nexport type DatabaseRequestStorage = {\n  uow: IUnitOfWork;\n};\n\n/**\n * Builder for database fragments that wraps the core fragment builder\n * and provides database-specific functionality.\n *\n * Database fragments always require FragnoPublicConfigWithDatabase (which includes databaseAdapter).\n */\nexport class DatabaseFragmentDefinitionBuilder<\n  TSchema extends AnySchema,\n  TConfig,\n  TDeps,\n  TBaseServices,\n  TServices,\n  TServiceDependencies,\n  TPrivateServices,\n  THooks extends HooksMap = {},\n  TServiceThisContext extends RequestThisContext = DatabaseHandlerContext,\n  THandlerThisContext extends RequestThisContext = DatabaseHandlerContext,\n  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},\n> {\n  // Store the base builder - we'll replace its storage and context setup when building\n  #baseBuilder: FragmentDefinitionBuilder<\n    TConfig,\n    FragnoPublicConfigWithDatabase,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    TServiceThisContext,\n    THandlerThisContext,\n    DatabaseRequestStorage,\n    TLinkedFragments\n  >;\n  #schema: TSchema;\n  #namespace: string;\n  #hooksFactory?: (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => THooks;\n\n  constructor(\n    baseBuilder: FragmentDefinitionBuilder<\n      TConfig,\n      FragnoPublicConfigWithDatabase,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices,\n      TServiceThisContext,\n      THandlerThisContext,\n      DatabaseRequestStorage,\n      TLinkedFragments\n    >,\n    schema: TSchema,\n    namespace?: string,\n    hooksFactory?: (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n    }) => THooks,\n  ) {\n    this.#baseBuilder = baseBuilder;\n    this.#schema = schema;\n    this.#namespace = namespace ?? baseBuilder.name;\n    this.#hooksFactory = hooksFactory;\n  }\n\n  /**\n   * Define dependencies for this database fragment.\n   * The context includes database adapter and ORM instance.\n   */\n  withDependencies<TNewDeps>(\n    fn: (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n      db: SimpleQueryInterface<TSchema>;\n      databaseAdapter: DatabaseAdapter<any>; // eslint-disable-line @typescript-eslint/no-explicit-any\n    }) => TNewDeps,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TNewDeps & ImplicitDatabaseDependencies<TSchema>,\n    {},\n    {},\n    TServiceDependencies,\n    {},\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    // Wrap user function to inject DB context\n    const wrappedFn = (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => {\n      const dbContext = createDatabaseContext(context.options, this.#schema, this.#namespace);\n\n      // Call user function with enriched context\n      const userDeps = fn({\n        config: context.config,\n        options: context.options,\n        db: dbContext.db,\n        databaseAdapter: dbContext.databaseAdapter,\n      });\n\n      // Create implicit dependencies\n      const createUow = () => dbContext.db.createUnitOfWork();\n      const implicitDeps: ImplicitDatabaseDependencies<TSchema> = {\n        db: dbContext.db,\n        schema: this.#schema,\n        namespace: this.#namespace,\n        createUnitOfWork: createUow,\n      };\n\n      return {\n        ...userDeps,\n        ...implicitDeps,\n      };\n    };\n\n    // Create new base builder with wrapped function\n    const newBaseBuilder = this.#baseBuilder.withDependencies(wrappedFn);\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  providesBaseService<TNewService>(\n    fn: ServiceConstructorFn<\n      TConfig,\n      FragnoPublicConfigWithDatabase,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TNewService,\n      TServiceThisContext\n    >,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TNewService,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.providesBaseService<TNewService>(fn);\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  providesService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n    fn: ServiceConstructorFn<\n      TConfig,\n      FragnoPublicConfigWithDatabase,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TService,\n      TServiceThisContext\n    >,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices & { [K in TServiceName]: TService },\n    TServiceDependencies,\n    TPrivateServices,\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.providesService<TServiceName, TService>(\n      serviceName,\n      fn,\n    );\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  /**\n   * Provide a private service that is only accessible to the fragment author.\n   * Private services are NOT exposed on the fragment instance, but can be used\n   * when defining other services (baseServices, namedServices, and other privateServices).\n   * Private services are instantiated in order, so earlier private services are available\n   * to later ones.\n   */\n  providesPrivateService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n    fn: ServiceConstructorFn<\n      TConfig,\n      FragnoPublicConfigWithDatabase,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TService,\n      TServiceThisContext\n    >,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices & { [K in TServiceName]: TService },\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.providesPrivateService<TServiceName, TService>(\n      serviceName,\n      fn,\n    );\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  /**\n   * Define durable hooks for this fragment.\n   * Hooks are automatically persisted and retried on failure.\n   *\n   * @param fn - Function that receives defineHook helper and returns a hooks map\n   * @returns Builder with hooks type set\n   *\n   * @example\n   * ```ts\n   * .provideHooks(({ defineHook, config }) => ({\n   *   onSubscribe: defineHook(async function (payload: { email: string }) {\n   *     // 'this' context available (HookServiceContext with nonce)\n   *     await config.onSubscribe?.(payload.email);\n   *   }),\n   * }))\n   * ```\n   */\n  provideHooks<TNewHooks extends HooksMap>(\n    fn: (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n      defineHook: <TPayload>(\n        hook: (this: HookContext, payload: TPayload) => void | Promise<void>,\n      ) => HookFn<TPayload>;\n    }) => TNewHooks,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    TNewHooks,\n    DatabaseServiceContext<TNewHooks>,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const defineHook = <TPayload>(\n      hook: (this: HookContext, payload: TPayload) => void | Promise<void>,\n    ): HookFn<TPayload> => {\n      return hook;\n    };\n\n    // Store the hooks factory - it will be called in build() with config/options\n    const hooksFactory = (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n    }) => {\n      return fn({\n        config: context.config,\n        options: context.options,\n        defineHook,\n      });\n    };\n\n    // Create new builder with hooks factory stored\n    // Cast is safe: we're only changing THooks and TServiceThisContext type parameters\n    const newBuilder = new DatabaseFragmentDefinitionBuilder(\n      this.#baseBuilder,\n      this.#schema,\n      this.#namespace,\n    ) as unknown as DatabaseFragmentDefinitionBuilder<\n      TSchema,\n      TConfig,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices,\n      TNewHooks,\n      DatabaseServiceContext<TNewHooks>,\n      THandlerThisContext,\n      TLinkedFragments\n    >;\n\n    newBuilder.#hooksFactory = hooksFactory;\n\n    return newBuilder;\n  }\n\n  /**\n   * Declare that this fragment uses a required service provided by the runtime.\n   * Delegates to the base builder.\n   */\n  usesService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies & { [K in TServiceName]: TService },\n    TPrivateServices,\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.usesService<TServiceName, TService>(serviceName);\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  /**\n   * Declare that this fragment uses an optional service provided by the runtime.\n   * Delegates to the base builder.\n   */\n  usesOptionalService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies & { [K in TServiceName]: TService | undefined },\n    TPrivateServices,\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.usesOptionalService<TServiceName, TService>(\n      serviceName,\n    );\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  /**\n   * Build the final database fragment definition.\n   * This includes the request context setup for UnitOfWork management.\n   * Note: TDeps already includes ImplicitDatabaseDependencies from withDatabase().\n   */\n  build(): FragmentDefinition<\n    TConfig,\n    FragnoPublicConfigWithDatabase,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    DatabaseServiceContext<THooks>,\n    DatabaseHandlerContext<THooks>,\n    DatabaseRequestStorage,\n    TLinkedFragments\n  > {\n    const baseDef = this.#baseBuilder.build();\n\n    // Ensure dependencies callback always exists for database fragments\n    // If no user dependencies were defined, create a minimal one that only adds implicit deps\n    const dependencies = (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n    }): TDeps => {\n      // In dry run mode, allow user deps to fail gracefully.\n      // This is critical for database fragments because the CLI needs access to the schema\n      // even when user dependencies (like API clients) can't be initialized.\n      // Without this, if user deps fail, we'd lose the implicit database dependencies\n      // (including schema), and the CLI couldn't extract schema information.\n      let userDeps;\n      try {\n        userDeps = baseDef.dependencies?.(context);\n      } catch (error) {\n        if (process.env[\"FRAGNO_INIT_DRY_RUN\"] === \"true\") {\n          console.warn(\n            \"Warning: Failed to initialize user dependencies in dry run mode:\",\n            error instanceof Error ? error.message : String(error),\n          );\n          userDeps = {};\n        } else {\n          throw error;\n        }\n      }\n\n      const { db } = createDatabaseContext(context.options, this.#schema, this.#namespace);\n\n      const implicitDeps: ImplicitDatabaseDependencies<TSchema> = {\n        db,\n        schema: this.#schema,\n        namespace: this.#namespace,\n        createUnitOfWork: () => db.createUnitOfWork(),\n      };\n\n      return {\n        ...userDeps,\n        ...implicitDeps,\n      } as TDeps;\n    };\n\n    // Use the adapter's shared context storage (all fragments using the same adapter share this storage)\n    const builderWithExternalStorage = this.#baseBuilder.withExternalRequestStorage(\n      ({ options }) => {\n        const dbContext = createDatabaseContext(options, this.#schema, this.#namespace);\n        return dbContext.databaseAdapter.contextStorage;\n      },\n    );\n\n    // Set up request storage to initialize the Unit of Work\n    const builderWithStorage = builderWithExternalStorage.withRequestStorage(\n      ({ options }): DatabaseRequestStorage => {\n        // Create database context - needed here to create the UOW\n        const dbContextForStorage = createDatabaseContext(options, this.#schema, this.#namespace);\n\n        // Create a new Unit of Work for this request\n        const uow: IUnitOfWork = dbContextForStorage.db.createUnitOfWork();\n\n        return { uow };\n      },\n    );\n\n    // Get the internal fragment factory from linked fragments (added by withDatabase)\n    // Cast is safe: withDatabase() guarantees this fragment exists and has the correct type\n    const internalFragmentFactory = baseDef.linkedFragments?.[\"_fragno_internal\"] as (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n    }) => InternalFragmentInstance;\n\n    const builderWithContext = builderWithStorage.withThisContext<\n      DatabaseServiceContext<THooks>,\n      DatabaseHandlerContext<THooks>\n    >(({ storage, config, options }) => {\n      // Create hooks config if hooks factory is defined\n      const hooksConfig = this.#hooksFactory\n        ? {\n            hooks: this.#hooksFactory({ config, options }),\n            namespace: this.#namespace,\n            internalFragment: internalFragmentFactory({ config, options }),\n          }\n        : undefined;\n\n      function forSchema<TSchema extends AnySchema>(\n        schema: TSchema,\n      ): TypedUnitOfWork<TSchema, [], unknown, THooks> {\n        const uow = storage.getStore()?.uow;\n        if (!uow) {\n          throw new Error(\n            \"No UnitOfWork in context. Service must be called within a route handler OR using `withUnitOfWork`.\",\n          );\n        }\n\n        return uow.restrict().forSchema<TSchema, THooks>(schema);\n      }\n\n      const serviceTx = async <\n        TSchema extends AnySchema,\n        TRetrievalResults extends unknown[],\n        TMutationResult = void,\n      >(\n        schema: TSchema,\n        callbacks: ServiceTxCallbacks<TSchema, TRetrievalResults, TMutationResult, THooks>,\n      ): Promise<AwaitedPromisesInObject<TMutationResult>> => {\n        const uow = storage.getStore()?.uow;\n        if (!uow) {\n          throw new Error(\n            \"No UnitOfWork in context. Service must be called within a route handler OR using `withUnitOfWork`.\",\n          );\n        }\n\n        return executeServiceTx(schema, callbacks, uow);\n      };\n\n      const serviceContext: DatabaseServiceContext<THooks> = {\n        uow: forSchema,\n        tx: serviceTx,\n      };\n\n      async function uow<TResult>(\n        callback: (context: {\n          forSchema: <S extends AnySchema, H extends HooksMap = THooks>(\n            schema: S,\n            hooks?: H,\n          ) => TypedUnitOfWork<S, [], unknown, H>;\n          executeRetrieve: () => Promise<void>;\n          executeMutate: () => Promise<void>;\n          nonce: string;\n          currentAttempt: number;\n        }) => Promise<TResult> | TResult,\n        execOptions?: Omit<ExecuteRestrictedUnitOfWorkOptions, \"createUnitOfWork\">,\n      ): Promise<AwaitedPromisesInObject<TResult>> {\n        const currentStorage = storage.getStore();\n        if (!currentStorage) {\n          throw new Error(\n            \"No storage in context. Handler must be called within a request context.\",\n          );\n        }\n\n        const wrappedCallback = async (context: {\n          forSchema: <S extends AnySchema, H extends HooksMap = THooks>(\n            schema: S,\n            hooks?: H,\n          ) => TypedUnitOfWork<S, [], unknown, H>;\n          executeRetrieve: () => Promise<void>;\n          executeMutate: () => Promise<void>;\n          nonce: string;\n          currentAttempt: number;\n        }): Promise<TResult> => {\n          return callback(context);\n        };\n\n        const userOnBeforeMutate = execOptions?.onBeforeMutate;\n        const userOnSuccess = execOptions?.onSuccess;\n\n        return executeRestrictedUnitOfWork(wrappedCallback, {\n          ...execOptions,\n          createUnitOfWork: () => {\n            currentStorage.uow.reset();\n            if (hooksConfig) {\n              currentStorage.uow.registerSchema(\n                hooksConfig.internalFragment.$internal.deps.schema,\n                hooksConfig.internalFragment.$internal.deps.namespace,\n              );\n            }\n            // Safe cast: currentStorage.uow is always a UnitOfWork instance\n            return currentStorage.uow as UnitOfWork;\n          },\n          onBeforeMutate: (uow) => {\n            if (hooksConfig) {\n              prepareHookMutations(uow, hooksConfig);\n            }\n            if (userOnBeforeMutate) {\n              userOnBeforeMutate(uow);\n            }\n          },\n          onSuccess: async (uow) => {\n            if (hooksConfig) {\n              await processHooks(hooksConfig);\n            }\n            if (userOnSuccess) {\n              await userOnSuccess(uow);\n            }\n          },\n        });\n      }\n\n      // Handler tx method with two overloads\n      function handlerTx<T extends readonly unknown[]>(\n        servicesFactory: () => readonly [...{ [K in keyof T]: Promise<T[K]> }],\n        execOptions?: Omit<ExecuteRestrictedUnitOfWorkOptions, \"createUnitOfWork\">,\n      ): Promise<{ [K in keyof T]: T[K] }>;\n      function handlerTx<TRetrieveResult, TMutationResult>(\n        callbacks: HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks>,\n        execOptions?: Omit<ExecuteRestrictedUnitOfWorkOptions, \"createUnitOfWork\">,\n      ): Promise<AwaitedPromisesInObject<TMutationResult>>;\n      async function handlerTx<T extends readonly unknown[], TRetrieveResult, TMutationResult>(\n        factoryOrCallbacks:\n          | (() => readonly [...{ [K in keyof T]: Promise<T[K]> }])\n          | HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks>,\n        execOptions?: Omit<ExecuteRestrictedUnitOfWorkOptions, \"createUnitOfWork\">,\n      ): Promise<{ [K in keyof T]: T[K] } | AwaitedPromisesInObject<TMutationResult>> {\n        const currentStorage = storage.getStore();\n        if (!currentStorage) {\n          throw new Error(\n            \"No storage in context. Handler must be called within a request context.\",\n          );\n        }\n\n        const userOnBeforeMutate = execOptions?.onBeforeMutate;\n        const userOnSuccess = execOptions?.onSuccess;\n\n        const createUow = () => {\n          currentStorage.uow.reset();\n\n          if (hooksConfig) {\n            currentStorage.uow.registerSchema(\n              hooksConfig.internalFragment.$internal.deps.schema,\n              hooksConfig.internalFragment.$internal.deps.namespace,\n            );\n          }\n          // Safe cast: currentStorage.uow is always a UnitOfWork instance\n          return currentStorage.uow as UnitOfWork;\n        };\n\n        const options: ExecuteRestrictedUnitOfWorkOptions = {\n          ...execOptions,\n          createUnitOfWork: createUow,\n          onBeforeMutate: (uow) => {\n            if (hooksConfig) {\n              prepareHookMutations(uow, hooksConfig);\n            }\n            if (userOnBeforeMutate) {\n              userOnBeforeMutate(uow);\n            }\n          },\n          onSuccess: async (uow) => {\n            if (hooksConfig) {\n              await processHooks(hooksConfig);\n            }\n            if (userOnSuccess) {\n              await userOnSuccess(uow);\n            }\n          },\n        };\n\n        // Check if it's a function (array syntax factory) or callbacks object (callback syntax)\n        if (typeof factoryOrCallbacks === \"function\") {\n          // Array syntax - factoryOrCallbacks is a factory function\n          return executeTxArray(\n            factoryOrCallbacks as () => readonly [...{ [K in keyof T]: Promise<T[K]> }],\n            options,\n          ) as Promise<{ [K in keyof T]: T[K] }>;\n        } else {\n          return executeTxCallbacks(\n            factoryOrCallbacks as HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks>,\n            options,\n          );\n        }\n      }\n\n      const handlerContext: DatabaseHandlerContext<THooks> = {\n        uow,\n        tx: handlerTx,\n      };\n\n      return { serviceContext, handlerContext };\n    });\n\n    // Build the final definition\n    const finalDef = builderWithContext.build();\n\n    // Return the complete definition with proper typing and dependencies\n    return {\n      ...finalDef,\n      dependencies,\n    };\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"db-fragment-definition-builder.js","names":["#baseBuilder","#schema","#namespace","#hooksFactory","implicitDeps: ImplicitDatabaseDependencies<TSchema>","serviceContext: DatabaseServiceContext<THooks>"],"sources":["../src/db-fragment-definition-builder.ts"],"sourcesContent":["import type { AnySchema } from \"./schema/create\";\nimport type { SimpleQueryInterface } from \"./query/simple-query-interface\";\nimport type { DatabaseAdapter } from \"./adapters/adapters\";\nimport type { IUnitOfWork } from \"./query/unit-of-work/unit-of-work\";\nimport type {\n  RequestThisContext,\n  FragnoPublicConfig,\n  AnyFragnoInstantiatedFragment,\n} from \"@fragno-dev/core\";\nimport {\n  FragmentDefinitionBuilder,\n  type FragmentDefinition,\n  type ServiceConstructorFn,\n} from \"@fragno-dev/core\";\nimport {\n  createServiceTxBuilder,\n  createHandlerTxBuilder,\n  ServiceTxBuilder,\n  HandlerTxBuilder,\n  type ExecuteTxOptions,\n} from \"./query/unit-of-work/execute-unit-of-work\";\nimport {\n  prepareHookMutations,\n  processHooks,\n  type HooksMap,\n  type HookFn,\n  type HookContext,\n} from \"./hooks/hooks\";\nimport type { InternalFragmentInstance } from \"./fragments/internal-fragment\";\n\n/**\n * Extended FragnoPublicConfig that includes a database adapter.\n * Use this type when creating fragments with database support.\n */\nexport type FragnoPublicConfigWithDatabase = FragnoPublicConfig & {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  databaseAdapter: DatabaseAdapter<any>;\n};\n\n/**\n * Implicit dependencies that database fragments get automatically.\n * These are injected without requiring explicit configuration.\n */\nexport type ImplicitDatabaseDependencies<TSchema extends AnySchema> = {\n  /**\n   * Database query engine for the fragment's schema.\n   */\n  db: SimpleQueryInterface<TSchema>;\n  /**\n   * The schema definition for this fragment.\n   */\n  schema: TSchema;\n  /**\n   * The database namespace for this fragment.\n   */\n  namespace: string;\n  /**\n   * Create a new Unit of Work for database operations.\n   */\n  createUnitOfWork: () => IUnitOfWork;\n};\n\n/**\n * Service context for database fragments - provides restricted UOW access without execute methods.\n */\nexport type DatabaseServiceContext<THooks extends HooksMap> = RequestThisContext & {\n  /**\n   * Create a service-level transaction builder using the fluent API.\n   * Returns a builder that can be chained with withServiceCalls, retrieve,\n   * transformRetrieve, mutate, transform, and build.\n   *\n   * @example\n   * ```ts\n   * return this.serviceTx(schema)\n   *   .withServiceCalls(() => [otherService.getData()])\n   *   .retrieve((uow) => uow.find(\"users\", ...))\n   *   .transformRetrieve(([users]) => users[0])\n   *   .mutate(({ uow, retrieveResult, serviceIntermediateResult }) =>\n   *     uow.create(\"records\", { ... })\n   *   )\n   *   .transform(({ mutateResult, serviceResult }) => ({ id: mutateResult }))\n   *   .build();\n   * ```\n   */\n  serviceTx<TSchema extends AnySchema>(\n    schema: TSchema,\n  ): ServiceTxBuilder<\n    TSchema,\n    readonly [],\n    [],\n    [],\n    unknown,\n    unknown,\n    false,\n    false,\n    false,\n    false,\n    THooks\n  >;\n};\n\n/**\n * Handler context for database fragments - provides UOW execution with automatic retry support.\n */\nexport type DatabaseHandlerContext<THooks extends HooksMap = {}> = RequestThisContext & {\n  /**\n   * Create a handler-level transaction builder using the fluent API.\n   * Returns a builder that can be chained with withServiceCalls, retrieve,\n   * transformRetrieve, mutate, transform, and execute.\n   *\n   * @example\n   * ```ts\n   * const result = await this.handlerTx()\n   *   .withServiceCalls(() => [userService.getUser(id)])\n   *   .mutate(({ forSchema, idempotencyKey, currentAttempt, serviceIntermediateResult }) => {\n   *     return forSchema(ordersSchema).create(\"orders\", { ... });\n   *   })\n   *   .transform(({ mutateResult, serviceResult }) => ({ ... }))\n   *   .execute();\n   * ```\n   */\n  handlerTx(\n    options?: Omit<ExecuteTxOptions, \"createUnitOfWork\">,\n  ): HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, THooks>;\n};\n\n/**\n * Database fragment context provided to user callbacks.\n */\nexport type DatabaseFragmentContext<TSchema extends AnySchema> = {\n  /**\n   * Database adapter instance.\n   */\n  databaseAdapter: DatabaseAdapter<any>; // eslint-disable-line @typescript-eslint/no-explicit-any\n  /**\n   * ORM query engine for the fragment's schema.\n   */\n  db: SimpleQueryInterface<TSchema>;\n};\n\n/**\n * Create database context from options.\n * This extracts the database adapter and creates the ORM instance.\n */\nfunction createDatabaseContext<TSchema extends AnySchema>(\n  options: FragnoPublicConfigWithDatabase,\n  schema: TSchema,\n  namespace: string,\n): DatabaseFragmentContext<TSchema> {\n  const databaseAdapter = options.databaseAdapter;\n\n  if (!databaseAdapter) {\n    throw new Error(\n      \"Database fragment requires a database adapter to be provided in options.databaseAdapter\",\n    );\n  }\n\n  const db = databaseAdapter.createQueryEngine(schema, namespace);\n\n  return { databaseAdapter, db };\n}\n\n/**\n * Storage type for database fragments - stores the Unit of Work.\n */\nexport type DatabaseRequestStorage = {\n  uow: IUnitOfWork;\n};\n\n/**\n * Builder for database fragments that wraps the core fragment builder\n * and provides database-specific functionality.\n *\n * Database fragments always require FragnoPublicConfigWithDatabase (which includes databaseAdapter).\n */\nexport class DatabaseFragmentDefinitionBuilder<\n  TSchema extends AnySchema,\n  TConfig,\n  TDeps,\n  TBaseServices,\n  TServices,\n  TServiceDependencies,\n  TPrivateServices,\n  THooks extends HooksMap = {},\n  TServiceThisContext extends RequestThisContext = DatabaseHandlerContext,\n  THandlerThisContext extends RequestThisContext = DatabaseHandlerContext,\n  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},\n> {\n  // Store the base builder - we'll replace its storage and context setup when building\n  #baseBuilder: FragmentDefinitionBuilder<\n    TConfig,\n    FragnoPublicConfigWithDatabase,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    TServiceThisContext,\n    THandlerThisContext,\n    DatabaseRequestStorage,\n    TLinkedFragments\n  >;\n  #schema: TSchema;\n  #namespace: string;\n  #hooksFactory?: (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => THooks;\n\n  constructor(\n    baseBuilder: FragmentDefinitionBuilder<\n      TConfig,\n      FragnoPublicConfigWithDatabase,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices,\n      TServiceThisContext,\n      THandlerThisContext,\n      DatabaseRequestStorage,\n      TLinkedFragments\n    >,\n    schema: TSchema,\n    namespace?: string,\n    hooksFactory?: (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n    }) => THooks,\n  ) {\n    this.#baseBuilder = baseBuilder;\n    this.#schema = schema;\n    this.#namespace = namespace ?? baseBuilder.name;\n    this.#hooksFactory = hooksFactory;\n  }\n\n  /**\n   * Define dependencies for this database fragment.\n   * The context includes database adapter and ORM instance.\n   */\n  withDependencies<TNewDeps>(\n    fn: (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n      db: SimpleQueryInterface<TSchema>;\n      databaseAdapter: DatabaseAdapter<any>; // eslint-disable-line @typescript-eslint/no-explicit-any\n    }) => TNewDeps,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TNewDeps & ImplicitDatabaseDependencies<TSchema>,\n    {},\n    {},\n    TServiceDependencies,\n    {},\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    // Wrap user function to inject DB context\n    const wrappedFn = (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => {\n      const dbContext = createDatabaseContext(context.options, this.#schema, this.#namespace);\n\n      // Call user function with enriched context\n      const userDeps = fn({\n        config: context.config,\n        options: context.options,\n        db: dbContext.db,\n        databaseAdapter: dbContext.databaseAdapter,\n      });\n\n      // Create implicit dependencies\n      const createUow = () => dbContext.db.createUnitOfWork();\n      const implicitDeps: ImplicitDatabaseDependencies<TSchema> = {\n        db: dbContext.db,\n        schema: this.#schema,\n        namespace: this.#namespace,\n        createUnitOfWork: createUow,\n      };\n\n      return {\n        ...userDeps,\n        ...implicitDeps,\n      };\n    };\n\n    // Create new base builder with wrapped function\n    const newBaseBuilder = this.#baseBuilder.withDependencies(wrappedFn);\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  providesBaseService<TNewService>(\n    fn: ServiceConstructorFn<\n      TConfig,\n      FragnoPublicConfigWithDatabase,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TNewService,\n      TServiceThisContext\n    >,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TNewService,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.providesBaseService<TNewService>(fn);\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  providesService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n    fn: ServiceConstructorFn<\n      TConfig,\n      FragnoPublicConfigWithDatabase,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TService,\n      TServiceThisContext\n    >,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices & { [K in TServiceName]: TService },\n    TServiceDependencies,\n    TPrivateServices,\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.providesService<TServiceName, TService>(\n      serviceName,\n      fn,\n    );\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  /**\n   * Provide a private service that is only accessible to the fragment author.\n   * Private services are NOT exposed on the fragment instance, but can be used\n   * when defining other services (baseServices, namedServices, and other privateServices).\n   * Private services are instantiated in order, so earlier private services are available\n   * to later ones.\n   */\n  providesPrivateService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n    fn: ServiceConstructorFn<\n      TConfig,\n      FragnoPublicConfigWithDatabase,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TService,\n      TServiceThisContext\n    >,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices & { [K in TServiceName]: TService },\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.providesPrivateService<TServiceName, TService>(\n      serviceName,\n      fn,\n    );\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  /**\n   * Define durable hooks for this fragment.\n   * Hooks are automatically persisted and retried on failure.\n   *\n   * @param fn - Function that receives defineHook helper and returns a hooks map\n   * @returns Builder with hooks type set\n   *\n   * @example\n   * ```ts\n   * .provideHooks(({ defineHook, config }) => ({\n   *   onSubscribe: defineHook(async function (payload: { email: string }) {\n   *     // 'this' context available (HookServiceContext with idempotencyKey)\n   *     await config.onSubscribe?.(payload.email);\n   *   }),\n   * }))\n   * ```\n   */\n  provideHooks<TNewHooks extends HooksMap>(\n    fn: (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n      defineHook: <TPayload>(\n        hook: (this: HookContext, payload: TPayload) => void | Promise<void>,\n      ) => HookFn<TPayload>;\n    }) => TNewHooks,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    TNewHooks,\n    DatabaseServiceContext<TNewHooks>,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const defineHook = <TPayload>(\n      hook: (this: HookContext, payload: TPayload) => void | Promise<void>,\n    ): HookFn<TPayload> => {\n      return hook;\n    };\n\n    // Store the hooks factory - it will be called in build() with config/options\n    const hooksFactory = (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n    }) => {\n      return fn({\n        config: context.config,\n        options: context.options,\n        defineHook,\n      });\n    };\n\n    // Create new builder with hooks factory stored\n    // Cast is safe: we're only changing THooks and TServiceThisContext type parameters\n    const newBuilder = new DatabaseFragmentDefinitionBuilder(\n      this.#baseBuilder,\n      this.#schema,\n      this.#namespace,\n    ) as unknown as DatabaseFragmentDefinitionBuilder<\n      TSchema,\n      TConfig,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices,\n      TNewHooks,\n      DatabaseServiceContext<TNewHooks>,\n      THandlerThisContext,\n      TLinkedFragments\n    >;\n\n    newBuilder.#hooksFactory = hooksFactory;\n\n    return newBuilder;\n  }\n\n  /**\n   * Declare that this fragment uses a required service provided by the runtime.\n   * Delegates to the base builder.\n   */\n  usesService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies & { [K in TServiceName]: TService },\n    TPrivateServices,\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.usesService<TServiceName, TService>(serviceName);\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  /**\n   * Declare that this fragment uses an optional service provided by the runtime.\n   * Delegates to the base builder.\n   */\n  usesOptionalService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n  ): DatabaseFragmentDefinitionBuilder<\n    TSchema,\n    TConfig,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies & { [K in TServiceName]: TService | undefined },\n    TPrivateServices,\n    THooks,\n    TServiceThisContext,\n    THandlerThisContext,\n    TLinkedFragments\n  > {\n    const newBaseBuilder = this.#baseBuilder.usesOptionalService<TServiceName, TService>(\n      serviceName,\n    );\n\n    return new DatabaseFragmentDefinitionBuilder(\n      newBaseBuilder,\n      this.#schema,\n      this.#namespace,\n      this.#hooksFactory,\n    );\n  }\n\n  /**\n   * Build the final database fragment definition.\n   * This includes the request context setup for UnitOfWork management.\n   * Note: TDeps already includes ImplicitDatabaseDependencies from withDatabase().\n   */\n  build(): FragmentDefinition<\n    TConfig,\n    FragnoPublicConfigWithDatabase,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    DatabaseServiceContext<THooks>,\n    DatabaseHandlerContext<THooks>,\n    DatabaseRequestStorage,\n    TLinkedFragments\n  > {\n    const baseDef = this.#baseBuilder.build();\n\n    // Ensure dependencies callback always exists for database fragments\n    // If no user dependencies were defined, create a minimal one that only adds implicit deps\n    const dependencies = (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n    }): TDeps => {\n      // In dry run mode, allow user deps to fail gracefully.\n      // This is critical for database fragments because the CLI needs access to the schema\n      // even when user dependencies (like API clients) can't be initialized.\n      // Without this, if user deps fail, we'd lose the implicit database dependencies\n      // (including schema), and the CLI couldn't extract schema information.\n      let userDeps;\n      try {\n        userDeps = baseDef.dependencies?.(context);\n      } catch (error) {\n        if (process.env[\"FRAGNO_INIT_DRY_RUN\"] === \"true\") {\n          console.warn(\n            \"Warning: Failed to initialize user dependencies in dry run mode:\",\n            error instanceof Error ? error.message : String(error),\n          );\n          userDeps = {};\n        } else {\n          throw error;\n        }\n      }\n\n      const { db } = createDatabaseContext(context.options, this.#schema, this.#namespace);\n\n      const implicitDeps: ImplicitDatabaseDependencies<TSchema> = {\n        db,\n        schema: this.#schema,\n        namespace: this.#namespace,\n        createUnitOfWork: () => db.createUnitOfWork(),\n      };\n\n      return {\n        ...userDeps,\n        ...implicitDeps,\n      } as TDeps;\n    };\n\n    // Use the adapter's shared context storage (all fragments using the same adapter share this storage)\n    const builderWithExternalStorage = this.#baseBuilder.withExternalRequestStorage(\n      ({ options }) => {\n        const dbContext = createDatabaseContext(options, this.#schema, this.#namespace);\n        return dbContext.databaseAdapter.contextStorage;\n      },\n    );\n\n    // Set up request storage to initialize the Unit of Work\n    const builderWithStorage = builderWithExternalStorage.withRequestStorage(\n      ({ options }): DatabaseRequestStorage => {\n        // Create database context - needed here to create the UOW\n        const dbContextForStorage = createDatabaseContext(options, this.#schema, this.#namespace);\n\n        // Create a new Unit of Work for this request\n        const uow: IUnitOfWork = dbContextForStorage.db.createUnitOfWork();\n\n        return { uow };\n      },\n    );\n\n    // Get the internal fragment factory from linked fragments (added by withDatabase)\n    // Cast is safe: withDatabase() guarantees this fragment exists and has the correct type\n    const internalFragmentFactory = baseDef.linkedFragments?.[\"_fragno_internal\"] as (context: {\n      config: TConfig;\n      options: FragnoPublicConfigWithDatabase;\n    }) => InternalFragmentInstance;\n\n    const builderWithContext = builderWithStorage.withThisContext<\n      DatabaseServiceContext<THooks>,\n      DatabaseHandlerContext<THooks>\n    >(({ storage, config, options }) => {\n      // Create hooks config if hooks factory is defined\n      const hooksConfig = this.#hooksFactory\n        ? {\n            hooks: this.#hooksFactory({ config, options }),\n            namespace: this.#namespace,\n            internalFragment: internalFragmentFactory({ config, options }),\n          }\n        : undefined;\n\n      // Builder API: serviceTx using createServiceTxBuilder\n      function serviceTx<TSchema extends AnySchema>(schema: TSchema) {\n        const uow = storage.getStore()?.uow;\n        if (!uow) {\n          throw new Error(\n            \"No UnitOfWork in context. Service must be called within a route handler OR using `withUnitOfWork`.\",\n          );\n        }\n        return createServiceTxBuilder<TSchema, THooks>(schema, uow, hooksConfig?.hooks);\n      }\n\n      const serviceContext: DatabaseServiceContext<THooks> = {\n        serviceTx,\n      };\n\n      // Builder API: handlerTx using createHandlerTxBuilder\n      function handlerTx(execOptions?: Omit<ExecuteTxOptions, \"createUnitOfWork\">) {\n        const currentStorage = storage.getStore();\n        if (!currentStorage) {\n          throw new Error(\n            \"No storage in context. Handler must be called within a request context.\",\n          );\n        }\n\n        const userOnBeforeMutate = execOptions?.onBeforeMutate;\n        const userOnAfterMutate = execOptions?.onAfterMutate;\n\n        return createHandlerTxBuilder<THooks>({\n          ...execOptions,\n          createUnitOfWork: () => {\n            currentStorage.uow.reset();\n            if (hooksConfig) {\n              currentStorage.uow.registerSchema(\n                hooksConfig.internalFragment.$internal.deps.schema,\n                hooksConfig.internalFragment.$internal.deps.namespace,\n              );\n            }\n            return currentStorage.uow;\n          },\n          onBeforeMutate: (uow) => {\n            if (hooksConfig) {\n              prepareHookMutations(uow, hooksConfig);\n            }\n            if (userOnBeforeMutate) {\n              userOnBeforeMutate(uow);\n            }\n          },\n          onAfterMutate: async (uow) => {\n            if (hooksConfig) {\n              await processHooks(hooksConfig);\n            }\n            if (userOnAfterMutate) {\n              await userOnAfterMutate(uow);\n            }\n          },\n        });\n      }\n\n      const handlerContext: DatabaseHandlerContext<THooks> = {\n        handlerTx,\n      };\n\n      return { serviceContext, handlerContext };\n    });\n\n    // Build the final definition\n    const finalDef = builderWithContext.build();\n\n    // Return the complete definition with proper typing and dependencies\n    return {\n      ...finalDef,\n      dependencies,\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/fragments/internal-fragment.d.ts

@@ -1,19 +1,38 @@
 import { AnyColumn, AnyRelation, Column, FragnoId, IdColumn, Index, Schema, Table } from "../schema/create.js";
 import { RetryPolicy } from "../query/unit-of-work/retry-policy.js";
+import { TxResult } from "../query/unit-of-work/execute-unit-of-work.js";
 import { DatabaseHandlerContext, DatabaseRequestStorage, DatabaseServiceContext, FragnoPublicConfigWithDatabase, ImplicitDatabaseDependencies } from "../db-fragment-definition-builder.js";
+import "../mod.js";
 import * as _fragno_dev_core0 from "@fragno-dev/core";
 import { InstantiatedFragmentFromDefinition } from "@fragno-dev/core";
 
 //#region src/fragments/internal-fragment.d.ts
 declare const internalFragmentDef: _fragno_dev_core0.FragmentDefinition<{}, FragnoPublicConfigWithDatabase, ImplicitDatabaseDependencies<Schema<Record<"fragno_db_settings", Table<Record<string, AnyColumn> & Record<"id", IdColumn<"varchar(30)", string | FragnoId | null, FragnoId>> & Record<"key", Column<"string", string, string>> & Record<"value", Column<"string", string, string>>, Record<string, AnyRelation>, Record<string, Index<AnyColumn[], readonly string[]>> & Record<"unique_key", Index<readonly [Column<"string", string, string>] & AnyColumn[], readonly ["key"]>>>> & Record<"fragno_hooks", Table<Record<string, AnyColumn> & Record<"id", IdColumn<"varchar(30)", string | FragnoId | null, FragnoId>> & Record<"namespace", Column<"string", string, string>> & Record<"hookName", Column<"string", string, string>> & Record<"payload", Column<"json", unknown, unknown>> & Record<"status", Column<"string", string, string>> & Record<"attempts", Column<"integer", number | null, number>> & Record<"maxAttempts", Column<"integer", number | null, number>> & Record<"lastAttemptAt", Column<"timestamp", Date | null, Date | null>> & Record<"nextRetryAt", Column<"timestamp", Date | null, Date | null>> & Record<"error", Column<"string", string | null, string | null>> & Record<"createdAt", Column<"timestamp", Date | null, Date>> & Record<"nonce", Column<"string", string, string>>, Record<string, AnyRelation>, Record<string, Index<AnyColumn[], readonly string[]>> & Record<"idx_namespace_status_retry", Index<readonly [Column<"string", string, string>, Column<"string", string, string>, Column<"timestamp", Date | null, Date | null>] & AnyColumn[], readonly ["namespace", "status", "nextRetryAt"]>> & Record<"idx_nonce", Index<readonly [Column<"string", string, string>] & AnyColumn[], readonly ["nonce"]>>>>>>, {}, {
   settingsService: {
-    get(namespace: string, key: string): Promise<{
+    /**
+     * Get a setting by namespace and key.
+     */
+    get(namespace: string, key: string): TxResult<{
+      id: FragnoId;
+      key: string;
+      value: string;
+    } | undefined, {
       id: FragnoId;
       key: string;
       value: string;
     } | undefined>;
-    set(namespace: string, key: string, value: string): Promise<void>;
-    delete(id: FragnoId): Promise<void>;
+    /**
+     * Set a setting value by namespace and key.
+     */
+    set(namespace: string, key: string, value: string): TxResult<void, {
+      id: FragnoId;
+      key: string;
+      value: string;
+    } | null>;
+    /**
+     * Delete a setting by ID.
+     */
+    delete(id: FragnoId): TxResult<void, void>;
   };
 } & {
   hookService: {
@@ -21,26 +40,93 @@ declare const internalFragmentDef: _fragno_dev_core0.FragmentDefinition<{}, Frag
      * Get pending hook events for processing.
      * Returns all pending events for the given namespace that are ready to be processed.
      */
-    getPendingHookEvents(namespace: string): Promise<{
+    getPendingHookEvents(namespace: string): TxResult<{
       id: FragnoId;
       hookName: string;
       payload: unknown;
       attempts: number;
       maxAttempts: number;
-      nonce: string;
+      idempotencyKey: string;
+    }[], {
+      id: FragnoId;
+      hookName: string;
+      payload: unknown;
+      attempts: number;
+      maxAttempts: number;
+      idempotencyKey: string;
     }[]>;
     /**
      * Mark a hook event as completed.
      */
-    markHookCompleted(eventId: FragnoId): void;
+    markHookCompleted(eventId: FragnoId): TxResult<void, void>;
     /**
      * Mark a hook event as failed and schedule next retry.
      */
-    markHookFailed(eventId: FragnoId, error: string, attempts: number, retryPolicy: RetryPolicy): void;
+    markHookFailed(eventId: FragnoId, error: string, attempts: number, retryPolicy: RetryPolicy): TxResult<void, void>;
     /**
      * Mark a hook event as processing (to prevent concurrent execution).
      */
-    markHookProcessing(eventId: FragnoId): void;
+    markHookProcessing(eventId: FragnoId): TxResult<void, void>;
+    /**
+     * Get a hook event by ID (for testing/verification purposes).
+     */
+    getHookById(eventId: FragnoId): TxResult<{
+      id: FragnoId;
+      namespace: string;
+      hookName: string;
+      payload: unknown;
+      status: string;
+      attempts: number;
+      maxAttempts: number;
+      lastAttemptAt: Date | null;
+      nextRetryAt: Date | null;
+      error: string | null;
+      createdAt: Date;
+      nonce: string;
+    } | undefined, {
+      id: FragnoId;
+      namespace: string;
+      hookName: string;
+      payload: unknown;
+      status: string;
+      attempts: number;
+      maxAttempts: number;
+      lastAttemptAt: Date | null;
+      nextRetryAt: Date | null;
+      error: string | null;
+      createdAt: Date;
+      nonce: string;
+    } | undefined>;
+    /**
+     * Get all hook events for a namespace (for testing/verification purposes).
+     */
+    getHooksByNamespace(namespace: string): TxResult<{
+      id: FragnoId;
+      namespace: string;
+      hookName: string;
+      payload: unknown;
+      status: string;
+      attempts: number;
+      maxAttempts: number;
+      lastAttemptAt: Date | null;
+      nextRetryAt: Date | null;
+      error: string | null;
+      createdAt: Date;
+      nonce: string;
+    }[], {
+      id: FragnoId;
+      namespace: string;
+      hookName: string;
+      payload: unknown;
+      status: string;
+      attempts: number;
+      maxAttempts: number;
+      lastAttemptAt: Date | null;
+      nextRetryAt: Date | null;
+      error: string | null;
+      createdAt: Date;
+      nonce: string;
+    }[]>;
   };
 }, {}, {}, DatabaseServiceContext<{}>, DatabaseHandlerContext<{}>, DatabaseRequestStorage, {}>;
 /**

package/dist/fragments/internal-fragment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-fragment.d.ts","names":[],"sources":["../../src/fragments/internal-fragment.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"internal-fragment.d.ts","names":[],"sources":["../../src/fragments/internal-fragment.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/fragments/internal-fragment.js

@@ -1,6 +1,6 @@
-import { column, idColumn, schema } from "../schema/create.js";
 import { FragmentDefinitionBuilder } from "../packages/fragno/dist/api/fragment-definition-builder.js";
 import { DatabaseFragmentDefinitionBuilder } from "../db-fragment-definition-builder.js";
+import { column, idColumn, schema } from "../schema/create.js";
 
 //#region src/fragments/internal-fragment.ts
 const SETTINGS_TABLE_NAME = "fragno_db_settings";
@@ -18,89 +18,90 @@ const internalSchema = schema((s) => {
 });
 const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(new FragmentDefinitionBuilder("$fragno-internal-fragment"), internalSchema, "").providesService("settingsService", ({ defineService }) => {
 	return defineService({
-		async get(namespace, key) {
+		get(namespace, key) {
 			const fullKey = `${namespace}.${key}`;
-			const [results] = await this.uow(internalSchema).find(SETTINGS_TABLE_NAME, (b) => b.whereIndex("unique_key", (eb) => eb("key", "=", fullKey))).retrievalPhase;
-			return results?.[0];
+			return this.serviceTx(internalSchema).retrieve((uow) => uow.findFirst(SETTINGS_TABLE_NAME, (b) => b.whereIndex("unique_key", (eb) => eb("key", "=", fullKey)))).transformRetrieve(([result]) => result ?? void 0).build();
 		},
-		async set(namespace, key, value) {
+		set(namespace, key, value) {
 			const fullKey = `${namespace}.${key}`;
-			const uow = this.uow(internalSchema);
-			const [existing] = await uow.find(SETTINGS_TABLE_NAME, (b) => b.whereIndex("unique_key", (eb) => eb("key", "=", fullKey))).retrievalPhase;
-			if (existing?.[0]) uow.update(SETTINGS_TABLE_NAME, existing[0].id, (b) => b.set({ value }).check());
-			else uow.create(SETTINGS_TABLE_NAME, {
-				key: fullKey,
-				value
-			});
-			await uow.mutationPhase;
+			return this.serviceTx(internalSchema).retrieve((uow) => uow.findFirst(SETTINGS_TABLE_NAME, (b) => b.whereIndex("unique_key", (eb) => eb("key", "=", fullKey)))).transformRetrieve(([result]) => result).mutate(({ uow, retrieveResult }) => {
+				if (retrieveResult) uow.update(SETTINGS_TABLE_NAME, retrieveResult.id, (b) => b.set({ value }).check());
+				else uow.create(SETTINGS_TABLE_NAME, {
+					key: fullKey,
+					value
+				});
+			}).build();
 		},
-		async delete(id) {
-			const uow = this.uow(internalSchema);
-			uow.delete(SETTINGS_TABLE_NAME, id);
-			await uow.mutationPhase;
+		delete(id) {
+			return this.serviceTx(internalSchema).mutate(({ uow }) => uow.delete(SETTINGS_TABLE_NAME, id)).build();
 		}
 	});
 }).providesService("hookService", ({ defineService }) => {
 	return defineService({
-		async getPendingHookEvents(namespace) {
-			const [events] = await this.uow(internalSchema).find("fragno_hooks", (b) => b.whereIndex("idx_namespace_status_retry", (eb) => eb.and(eb("namespace", "=", namespace), eb("status", "=", "pending")))).retrievalPhase;
-			const now = /* @__PURE__ */ new Date();
-			return events.filter((event) => {
-				if (!event.nextRetryAt) return true;
-				return event.nextRetryAt <= now;
-			}).map((event) => ({
-				id: event.id,
-				hookName: event.hookName,
-				payload: event.payload,
-				attempts: event.attempts,
-				maxAttempts: event.maxAttempts,
-				nonce: event.nonce
-			}));
+		getPendingHookEvents(namespace) {
+			return this.serviceTx(internalSchema).retrieve((uow) => uow.find("fragno_hooks", (b) => b.whereIndex("idx_namespace_status_retry", (eb) => eb.and(eb("namespace", "=", namespace), eb("status", "=", "pending"))))).transformRetrieve(([events]) => {
+				const now = /* @__PURE__ */ new Date();
+				return events.filter((event) => {
+					if (!event.nextRetryAt) return true;
+					return event.nextRetryAt <= now;
+				}).map((event) => ({
+					id: event.id,
+					hookName: event.hookName,
+					payload: event.payload,
+					attempts: event.attempts,
+					maxAttempts: event.maxAttempts,
+					idempotencyKey: event.nonce
+				}));
+			}).build();
 		},
 		markHookCompleted(eventId) {
-			this.uow(internalSchema).update("fragno_hooks", eventId, (b) => b.set({
+			return this.serviceTx(internalSchema).mutate(({ uow }) => uow.update("fragno_hooks", eventId, (b) => b.set({
 				status: "completed",
 				lastAttemptAt: /* @__PURE__ */ new Date()
-			}).check());
+			}).check())).build();
 		},
 		markHookFailed(eventId, error, attempts, retryPolicy) {
-			const uow = this.uow(internalSchema);
 			const newAttempts = attempts + 1;
-			if (retryPolicy.shouldRetry(newAttempts - 1)) {
-				const delayMs = retryPolicy.getDelayMs(newAttempts - 1);
-				const nextRetryAt = new Date(Date.now() + delayMs);
-				uow.update("fragno_hooks", eventId, (b) => b.set({
-					status: "pending",
+			const shouldRetry = retryPolicy.shouldRetry(newAttempts - 1);
+			return this.serviceTx(internalSchema).mutate(({ uow }) => {
+				if (shouldRetry) {
+					const delayMs = retryPolicy.getDelayMs(newAttempts - 1);
+					const nextRetryAt = new Date(Date.now() + delayMs);
+					uow.update("fragno_hooks", eventId, (b) => b.set({
+						status: "pending",
+						attempts: newAttempts,
+						lastAttemptAt: /* @__PURE__ */ new Date(),
+						nextRetryAt,
+						error
+					}).check());
+				} else uow.update("fragno_hooks", eventId, (b) => b.set({
+					status: "failed",
 					attempts: newAttempts,
 					lastAttemptAt: /* @__PURE__ */ new Date(),
-					nextRetryAt,
 					error
 				}).check());
-			} else uow.update("fragno_hooks", eventId, (b) => b.set({
-				status: "failed",
-				attempts: newAttempts,
-				lastAttemptAt: /* @__PURE__ */ new Date(),
-				error
-			}).check());
+			}).build();
 		},
 		markHookProcessing(eventId) {
-			this.uow(internalSchema).update("fragno_hooks", eventId, (b) => b.set({
+			return this.serviceTx(internalSchema).mutate(({ uow }) => uow.update("fragno_hooks", eventId, (b) => b.set({
 				status: "processing",
 				lastAttemptAt: /* @__PURE__ */ new Date()
-			}).check());
+			}).check())).build();
+		},
+		getHookById(eventId) {
+			return this.serviceTx(internalSchema).retrieve((uow) => uow.findFirst("fragno_hooks", (b) => b.whereIndex("primary", (eb) => eb("id", "=", eventId)))).transformRetrieve(([result]) => result ?? void 0).build();
+		},
+		getHooksByNamespace(namespace) {
+			return this.serviceTx(internalSchema).retrieve((uow) => uow.find("fragno_hooks", (b) => b.whereIndex("idx_namespace_status_retry", (eb) => eb("namespace", "=", namespace)))).transformRetrieve(([events]) => events).build();
 		}
 	});
 }).build();
 async function getSchemaVersionFromDatabase(fragment, namespace) {
 	try {
-		return await fragment.inContext(async function() {
-			const version = await this.uow(async ({ executeRetrieve }) => {
-				const version$1 = fragment.services.settingsService.get(namespace, "schema_version");
-				await executeRetrieve();
-				return version$1;
-			});
-			return version ? parseInt(version.value, 10) : 0;
+		const setting = await fragment.inContext(async function() {
+			return await this.handlerTx().withServiceCalls(() => [fragment.services.settingsService.get(namespace, "schema_version")]).transform(({ serviceResult: [result] }) => result).execute();
 		});
+		return setting ? parseInt(setting.value, 10) : 0;
 	} catch {
 		return 0;
 	}

package/dist/fragments/internal-fragment.js.map

@@ -1 +1 @@
-{"version":3,"file":"internal-fragment.js","names":["version"],"sources":["../../src/fragments/internal-fragment.ts"],"sourcesContent":["import { FragmentDefinitionBuilder } from \"@fragno-dev/core\";\nimport type { InstantiatedFragmentFromDefinition } from \"@fragno-dev/core\";\nimport {\n  DatabaseFragmentDefinitionBuilder,\n  type DatabaseHandlerContext,\n  type DatabaseRequestStorage,\n  type DatabaseServiceContext,\n  type FragnoPublicConfigWithDatabase,\n  type ImplicitDatabaseDependencies,\n} from \"../db-fragment-definition-builder\";\nimport type { FragnoId } from \"../schema/create\";\nimport { schema, idColumn, column } from \"../schema/create\";\nimport type { RetryPolicy } from \"../query/unit-of-work/retry-policy\";\n\n// Constants for Fragno's internal settings table\nexport const SETTINGS_TABLE_NAME = \"fragno_db_settings\" as const;\n// FIXME: In some places we simply use empty string \"\" as namespace, which is not correct.\nexport const SETTINGS_NAMESPACE = \"fragno-db-settings\" as const;\n\nexport const internalSchema = schema((s) => {\n  return s\n    .addTable(SETTINGS_TABLE_NAME, (t) => {\n      return t\n        .addColumn(\"id\", idColumn())\n        .addColumn(\"key\", column(\"string\"))\n        .addColumn(\"value\", column(\"string\"))\n        .createIndex(\"unique_key\", [\"key\"], { unique: true });\n    })\n    .addTable(\"fragno_hooks\", (t) => {\n      return t\n        .addColumn(\"id\", idColumn())\n        .addColumn(\"namespace\", column(\"string\"))\n        .addColumn(\"hookName\", column(\"string\"))\n        .addColumn(\"payload\", column(\"json\"))\n        .addColumn(\"status\", column(\"string\")) // \"pending\" | \"processing\" | \"completed\" | \"failed\"\n        .addColumn(\"attempts\", column(\"integer\").defaultTo(0))\n        .addColumn(\"maxAttempts\", column(\"integer\").defaultTo(5))\n        .addColumn(\"lastAttemptAt\", column(\"timestamp\").nullable())\n        .addColumn(\"nextRetryAt\", column(\"timestamp\").nullable())\n        .addColumn(\"error\", column(\"string\").nullable())\n        .addColumn(\n          \"createdAt\",\n          column(\"timestamp\").defaultTo((b) => b.now()),\n        )\n        .addColumn(\"nonce\", column(\"string\"))\n        .createIndex(\"idx_namespace_status_retry\", [\"namespace\", \"status\", \"nextRetryAt\"])\n        .createIndex(\"idx_nonce\", [\"nonce\"]);\n    });\n});\n\n// This uses DatabaseFragmentDefinitionBuilder directly\n// to avoid circular dependency (it doesn't need to link to itself)\nexport const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(\n  new FragmentDefinitionBuilder<\n    {},\n    FragnoPublicConfigWithDatabase,\n    ImplicitDatabaseDependencies<typeof internalSchema>,\n    {},\n    {},\n    {},\n    {},\n    DatabaseServiceContext<{}>,\n    DatabaseHandlerContext,\n    DatabaseRequestStorage\n  >(\"$fragno-internal-fragment\"),\n  internalSchema,\n  \"\", // intentionally blank namespace so there is no prefix\n)\n  .providesService(\"settingsService\", ({ defineService }) => {\n    return defineService({\n      async get(\n        namespace: string,\n        key: string,\n      ): Promise<{ id: FragnoId; key: string; value: string } | undefined> {\n        const fullKey = `${namespace}.${key}`;\n        const uow = this.uow(internalSchema).find(SETTINGS_TABLE_NAME, (b) =>\n          b.whereIndex(\"unique_key\", (eb) => eb(\"key\", \"=\", fullKey)),\n        );\n        const [results] = await uow.retrievalPhase;\n        return results?.[0];\n      },\n\n      async set(namespace: string, key: string, value: string) {\n        const fullKey = `${namespace}.${key}`;\n        const uow = this.uow(internalSchema);\n\n        // First, find if the key already exists\n        const findUow = uow.find(SETTINGS_TABLE_NAME, (b) =>\n          b.whereIndex(\"unique_key\", (eb) => eb(\"key\", \"=\", fullKey)),\n        );\n        const [existing] = await findUow.retrievalPhase;\n\n        if (existing?.[0]) {\n          uow.update(SETTINGS_TABLE_NAME, existing[0].id, (b) => b.set({ value }).check());\n        } else {\n          uow.create(SETTINGS_TABLE_NAME, {\n            key: fullKey,\n            value,\n          });\n        }\n\n        // Await mutation phase - will throw if mutation fails\n        await uow.mutationPhase;\n      },\n\n      async delete(id: FragnoId) {\n        const uow = this.uow(internalSchema);\n        uow.delete(SETTINGS_TABLE_NAME, id);\n        await uow.mutationPhase;\n      },\n    });\n  })\n  .providesService(\"hookService\", ({ defineService }) => {\n    return defineService({\n      /**\n       * Get pending hook events for processing.\n       * Returns all pending events for the given namespace that are ready to be processed.\n       */\n      async getPendingHookEvents(namespace: string): Promise<\n        {\n          id: FragnoId;\n          hookName: string;\n          payload: unknown;\n          attempts: number;\n          maxAttempts: number;\n          nonce: string;\n        }[]\n      > {\n        const uow = this.uow(internalSchema).find(\"fragno_hooks\", (b) =>\n          b.whereIndex(\"idx_namespace_status_retry\", (eb) =>\n            eb.and(eb(\"namespace\", \"=\", namespace), eb(\"status\", \"=\", \"pending\")),\n          ),\n        );\n\n        const [events] = await uow.retrievalPhase;\n\n        // Filter for pending status and events ready for retry\n        const now = new Date();\n        const ready = events.filter((event) => {\n          // FIXME(Wilco): this should be handled by the database query, but there seems to be an issue.\n          if (!event.nextRetryAt) {\n            return true; // Newly created events (nextRetryAt = null) are ready\n          }\n          return event.nextRetryAt <= now; // Only include if retry time has passed\n        });\n\n        return ready.map((event) => ({\n          id: event.id,\n          hookName: event.hookName,\n          payload: event.payload,\n          attempts: event.attempts,\n          maxAttempts: event.maxAttempts,\n          nonce: event.nonce,\n        }));\n      },\n\n      /**\n       * Mark a hook event as completed.\n       */\n      markHookCompleted(eventId: FragnoId): void {\n        const uow = this.uow(internalSchema);\n        uow.update(\"fragno_hooks\", eventId, (b) =>\n          b.set({ status: \"completed\", lastAttemptAt: new Date() }).check(),\n        );\n      },\n\n      /**\n       * Mark a hook event as failed and schedule next retry.\n       */\n      markHookFailed(\n        eventId: FragnoId,\n        error: string,\n        attempts: number,\n        retryPolicy: RetryPolicy,\n      ): void {\n        const uow = this.uow(internalSchema);\n\n        const newAttempts = attempts + 1;\n        const shouldRetry = retryPolicy.shouldRetry(newAttempts - 1);\n\n        if (shouldRetry) {\n          const delayMs = retryPolicy.getDelayMs(newAttempts - 1);\n          const nextRetryAt = new Date(Date.now() + delayMs);\n          uow.update(\"fragno_hooks\", eventId, (b) =>\n            b\n              .set({\n                status: \"pending\",\n                attempts: newAttempts,\n                lastAttemptAt: new Date(),\n                nextRetryAt,\n                error,\n              })\n              .check(),\n          );\n        } else {\n          uow.update(\"fragno_hooks\", eventId, (b) =>\n            b\n              .set({\n                status: \"failed\",\n                attempts: newAttempts,\n                lastAttemptAt: new Date(),\n                error,\n              })\n              .check(),\n          );\n        }\n      },\n\n      /**\n       * Mark a hook event as processing (to prevent concurrent execution).\n       */\n      markHookProcessing(eventId: FragnoId): void {\n        const uow = this.uow(internalSchema);\n        uow.update(\"fragno_hooks\", eventId, (b) =>\n          b.set({ status: \"processing\", lastAttemptAt: new Date() }).check(),\n        );\n      },\n    });\n  })\n  .build();\n\n/**\n * Type representing an instantiated internal fragment.\n * This is the fragment that manages Fragno's internal settings table.\n */\nexport type InternalFragmentInstance = InstantiatedFragmentFromDefinition<\n  typeof internalFragmentDef\n>;\n\nexport async function getSchemaVersionFromDatabase(\n  fragment: InternalFragmentInstance,\n  namespace: string,\n): Promise<number> {\n  try {\n    const version = await fragment.inContext(async function () {\n      const version = await this.uow(async ({ executeRetrieve }) => {\n        const version = fragment.services.settingsService.get(namespace, \"schema_version\");\n        await executeRetrieve();\n        return version;\n      });\n\n      return version ? parseInt(version.value, 10) : 0;\n    });\n    return version;\n  } catch {\n    return 0;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"internal-fragment.js","names":[],"sources":["../../src/fragments/internal-fragment.ts"],"sourcesContent":["import { FragmentDefinitionBuilder } from \"@fragno-dev/core\";\nimport type { InstantiatedFragmentFromDefinition } from \"@fragno-dev/core\";\nimport {\n  DatabaseFragmentDefinitionBuilder,\n  type DatabaseHandlerContext,\n  type DatabaseRequestStorage,\n  type DatabaseServiceContext,\n  type FragnoPublicConfigWithDatabase,\n  type ImplicitDatabaseDependencies,\n} from \"../db-fragment-definition-builder\";\nimport type { FragnoId } from \"../schema/create\";\nimport { schema, idColumn, column } from \"../schema/create\";\nimport type { RetryPolicy } from \"../query/unit-of-work/retry-policy\";\n\n// Constants for Fragno's internal settings table\nexport const SETTINGS_TABLE_NAME = \"fragno_db_settings\" as const;\n// FIXME: In some places we simply use empty string \"\" as namespace, which is not correct.\nexport const SETTINGS_NAMESPACE = \"fragno-db-settings\" as const;\n\nexport const internalSchema = schema((s) => {\n  return s\n    .addTable(SETTINGS_TABLE_NAME, (t) => {\n      return t\n        .addColumn(\"id\", idColumn())\n        .addColumn(\"key\", column(\"string\"))\n        .addColumn(\"value\", column(\"string\"))\n        .createIndex(\"unique_key\", [\"key\"], { unique: true });\n    })\n    .addTable(\"fragno_hooks\", (t) => {\n      return t\n        .addColumn(\"id\", idColumn())\n        .addColumn(\"namespace\", column(\"string\"))\n        .addColumn(\"hookName\", column(\"string\"))\n        .addColumn(\"payload\", column(\"json\"))\n        .addColumn(\"status\", column(\"string\")) // \"pending\" | \"processing\" | \"completed\" | \"failed\"\n        .addColumn(\"attempts\", column(\"integer\").defaultTo(0))\n        .addColumn(\"maxAttempts\", column(\"integer\").defaultTo(5))\n        .addColumn(\"lastAttemptAt\", column(\"timestamp\").nullable())\n        .addColumn(\"nextRetryAt\", column(\"timestamp\").nullable())\n        .addColumn(\"error\", column(\"string\").nullable())\n        .addColumn(\n          \"createdAt\",\n          column(\"timestamp\").defaultTo((b) => b.now()),\n        )\n        .addColumn(\"nonce\", column(\"string\"))\n        .createIndex(\"idx_namespace_status_retry\", [\"namespace\", \"status\", \"nextRetryAt\"])\n        .createIndex(\"idx_nonce\", [\"nonce\"]);\n    });\n});\n\n// This uses DatabaseFragmentDefinitionBuilder directly\n// to avoid circular dependency (it doesn't need to link to itself)\nexport const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(\n  new FragmentDefinitionBuilder<\n    {},\n    FragnoPublicConfigWithDatabase,\n    ImplicitDatabaseDependencies<typeof internalSchema>,\n    {},\n    {},\n    {},\n    {},\n    DatabaseServiceContext<{}>,\n    DatabaseHandlerContext,\n    DatabaseRequestStorage\n  >(\"$fragno-internal-fragment\"),\n  internalSchema,\n  \"\", // intentionally blank namespace so there is no prefix\n)\n  .providesService(\"settingsService\", ({ defineService }) => {\n    return defineService({\n      /**\n       * Get a setting by namespace and key.\n       */\n      get(namespace: string, key: string) {\n        const fullKey = `${namespace}.${key}`;\n        return this.serviceTx(internalSchema)\n          .retrieve((uow) =>\n            uow.findFirst(SETTINGS_TABLE_NAME, (b) =>\n              b.whereIndex(\"unique_key\", (eb) => eb(\"key\", \"=\", fullKey)),\n            ),\n          )\n          .transformRetrieve(\n            ([result]): { id: FragnoId; key: string; value: string } | undefined =>\n              result ?? undefined,\n          )\n          .build();\n      },\n\n      /**\n       * Set a setting value by namespace and key.\n       */\n      set(namespace: string, key: string, value: string) {\n        const fullKey = `${namespace}.${key}`;\n        return this.serviceTx(internalSchema)\n          .retrieve((uow) =>\n            uow.findFirst(SETTINGS_TABLE_NAME, (b) =>\n              b.whereIndex(\"unique_key\", (eb) => eb(\"key\", \"=\", fullKey)),\n            ),\n          )\n          .transformRetrieve(([result]) => result)\n          .mutate(({ uow, retrieveResult }) => {\n            if (retrieveResult) {\n              uow.update(SETTINGS_TABLE_NAME, retrieveResult.id, (b) => b.set({ value }).check());\n            } else {\n              uow.create(SETTINGS_TABLE_NAME, {\n                key: fullKey,\n                value,\n              });\n            }\n          })\n          .build();\n      },\n\n      /**\n       * Delete a setting by ID.\n       */\n      delete(id: FragnoId) {\n        return this.serviceTx(internalSchema)\n          .mutate(({ uow }) => uow.delete(SETTINGS_TABLE_NAME, id))\n          .build();\n      },\n    });\n  })\n  .providesService(\"hookService\", ({ defineService }) => {\n    return defineService({\n      /**\n       * Get pending hook events for processing.\n       * Returns all pending events for the given namespace that are ready to be processed.\n       */\n      getPendingHookEvents(namespace: string) {\n        return this.serviceTx(internalSchema)\n          .retrieve((uow) =>\n            uow.find(\"fragno_hooks\", (b) =>\n              b.whereIndex(\"idx_namespace_status_retry\", (eb) =>\n                eb.and(eb(\"namespace\", \"=\", namespace), eb(\"status\", \"=\", \"pending\")),\n              ),\n            ),\n          )\n          .transformRetrieve(([events]) => {\n            const now = new Date();\n            // FIXME(Wilco): this should be handled by the database query, but there seems to be an issue.\n            const ready = events.filter((event) => {\n              if (!event.nextRetryAt) {\n                return true; // Newly created events (nextRetryAt = null) are ready\n              }\n              return event.nextRetryAt <= now; // Only include if retry time has passed\n            });\n\n            return ready.map((event) => ({\n              id: event.id,\n              hookName: event.hookName,\n              payload: event.payload as unknown,\n              attempts: event.attempts,\n              maxAttempts: event.maxAttempts,\n              idempotencyKey: event.nonce,\n            }));\n          })\n          .build();\n      },\n\n      /**\n       * Mark a hook event as completed.\n       */\n      markHookCompleted(eventId: FragnoId) {\n        return this.serviceTx(internalSchema)\n          .mutate(({ uow }) =>\n            uow.update(\"fragno_hooks\", eventId, (b) =>\n              b.set({ status: \"completed\", lastAttemptAt: new Date() }).check(),\n            ),\n          )\n          .build();\n      },\n\n      /**\n       * Mark a hook event as failed and schedule next retry.\n       */\n      markHookFailed(eventId: FragnoId, error: string, attempts: number, retryPolicy: RetryPolicy) {\n        const newAttempts = attempts + 1;\n        const shouldRetry = retryPolicy.shouldRetry(newAttempts - 1);\n\n        return this.serviceTx(internalSchema)\n          .mutate(({ uow }) => {\n            if (shouldRetry) {\n              const delayMs = retryPolicy.getDelayMs(newAttempts - 1);\n              const nextRetryAt = new Date(Date.now() + delayMs);\n              uow.update(\"fragno_hooks\", eventId, (b) =>\n                b\n                  .set({\n                    status: \"pending\",\n                    attempts: newAttempts,\n                    lastAttemptAt: new Date(),\n                    nextRetryAt,\n                    error,\n                  })\n                  .check(),\n              );\n            } else {\n              uow.update(\"fragno_hooks\", eventId, (b) =>\n                b\n                  .set({\n                    status: \"failed\",\n                    attempts: newAttempts,\n                    lastAttemptAt: new Date(),\n                    error,\n                  })\n                  .check(),\n              );\n            }\n          })\n          .build();\n      },\n\n      /**\n       * Mark a hook event as processing (to prevent concurrent execution).\n       */\n      markHookProcessing(eventId: FragnoId) {\n        return this.serviceTx(internalSchema)\n          .mutate(({ uow }) =>\n            uow.update(\"fragno_hooks\", eventId, (b) =>\n              b.set({ status: \"processing\", lastAttemptAt: new Date() }).check(),\n            ),\n          )\n          .build();\n      },\n\n      /**\n       * Get a hook event by ID (for testing/verification purposes).\n       */\n      getHookById(eventId: FragnoId) {\n        return this.serviceTx(internalSchema)\n          .retrieve((uow) =>\n            uow.findFirst(\"fragno_hooks\", (b) =>\n              b.whereIndex(\"primary\", (eb) => eb(\"id\", \"=\", eventId)),\n            ),\n          )\n          .transformRetrieve(([result]) => result ?? undefined)\n          .build();\n      },\n\n      /**\n       * Get all hook events for a namespace (for testing/verification purposes).\n       */\n      getHooksByNamespace(namespace: string) {\n        return this.serviceTx(internalSchema)\n          .retrieve((uow) =>\n            uow.find(\"fragno_hooks\", (b) =>\n              b.whereIndex(\"idx_namespace_status_retry\", (eb) => eb(\"namespace\", \"=\", namespace)),\n            ),\n          )\n          .transformRetrieve(([events]) => events)\n          .build();\n      },\n    });\n  })\n  .build();\n\n/**\n * Type representing an instantiated internal fragment.\n * This is the fragment that manages Fragno's internal settings table.\n */\nexport type InternalFragmentInstance = InstantiatedFragmentFromDefinition<\n  typeof internalFragmentDef\n>;\n\nexport async function getSchemaVersionFromDatabase(\n  fragment: InternalFragmentInstance,\n  namespace: string,\n): Promise<number> {\n  try {\n    const setting = await fragment.inContext(async function () {\n      return await this.handlerTx()\n        .withServiceCalls(\n          () => [fragment.services.settingsService.get(namespace, \"schema_version\")] as const,\n        )\n        .transform(({ serviceResult: [result] }) => result)\n        .execute();\n    });\n    return setting ? parseInt(setting.value, 10) : 0;\n  } catch {\n    return 0;\n  }\n}\n"],"mappings":"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"}

package/dist/hooks/hooks.d.ts

@@ -1,17 +1,19 @@
 import { RetryPolicy } from "../query/unit-of-work/retry-policy.js";
+import "../fragments/internal-fragment.js";
+import "../query/unit-of-work/unit-of-work.js";
 
 //#region src/hooks/hooks.d.ts
 
 /**
  * Context available in hook functions via `this`.
- * Contains the nonce for idempotency and database access.
+ * Contains the idempotency key for idempotency and database access.
  */
 interface HookContext {
   /**
-   * Unique nonce for this transaction.
+   * Unique idempotency key for this transaction.
    * Use this for idempotency checks in your hook implementation.
    */
-  nonce: string;
+  idempotencyKey: string;
 }
 /**
  * A hook function signature.

package/dist/hooks/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","names":[],"sources":["../../src/hooks/hooks.ts"],"sourcesContent":[],"mappings":";;;;AASA;AAYA;AAOA;AAKA;AAA6B,UAxBZ,WAAA,CAwBY;EAAU;;;AAKvC;EAYiB,KAAA,EAAA,MAAA;;;;;;KA7BL,uCAAuC,oBAAoB;;;;;KAO3D,QAAA,GAAW,eAAe;;;;KAK1B,iBAAiB,UAAU,kBAAkB;;;;UAKxC,kBAAA;;;;;gBAKD;;;;;;UAOC,aAAA;;;YAGL"}
+{"version":3,"file":"hooks.d.ts","names":[],"sources":["../../src/hooks/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAUA;AAYA;AAOY,UAnBK,WAAA,CAmBqB;EAK1B;;;;EAA8C,cAAA,EAAA,MAAA;AAK1D;AAYA;;;;KA7BY,uCAAuC,oBAAoB;;;;;KAO3D,QAAA,GAAW,eAAe;;;;KAK1B,iBAAiB,UAAU,kBAAkB;;;;UAKxC,kBAAA;;;;;gBAKD;;;;;;UAOC,aAAA;;;YAGL"}