@fragno-dev/db 0.2.0 → 0.2.2

package/dist/hooks/hooks.js

@@ -25,7 +25,7 @@ function prepareHookMutations(uow, config) {
 			lastAttemptAt: null,
 			nextRetryAt: null,
 			error: null,
-			nonce: uow.nonce
+			nonce: uow.idempotencyKey
 		});
 	}
 }
@@ -36,50 +36,51 @@ function prepareHookMutations(uow, config) {
 async function processHooks(config) {
 	const { hooks, namespace, internalFragment, defaultRetryPolicy } = config;
 	const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
+	const pendingEvents = await internalFragment.inContext(async function() {
+		return await this.handlerTx().withServiceCalls(() => [internalFragment.services.hookService.getPendingHookEvents(namespace)]).transform(({ serviceResult: [events] }) => events).execute();
+	});
+	if (pendingEvents.length === 0) return;
+	const processedEvents = await Promise.allSettled(pendingEvents.map(async (event) => {
+		const hookFn = hooks[event.hookName];
+		if (!hookFn) return {
+			eventId: event.id,
+			status: "failed",
+			error: `Hook '${event.hookName}' not found in hooks map`,
+			attempts: event.attempts,
+			maxAttempts: event.maxAttempts
+		};
+		try {
+			const hookContext = { idempotencyKey: event.idempotencyKey };
+			await hookFn.call(hookContext, event.payload);
+			return {
+				eventId: event.id,
+				status: "completed"
+			};
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			return {
+				eventId: event.id,
+				status: "failed",
+				error: errorMessage,
+				attempts: event.attempts,
+				maxAttempts: event.maxAttempts
+			};
+		}
+	}));
 	await internalFragment.inContext(async function() {
-		return await this.uow(async ({ executeRetrieve, executeMutate }) => {
-			const pendingEventsPromise = internalFragment.services.hookService.getPendingHookEvents(namespace);
-			await executeRetrieve();
-			const pendingEvents = await pendingEventsPromise;
-			if (pendingEvents.length === 0) return;
-			const processedEvents = await Promise.allSettled(pendingEvents.map(async (event) => {
-				const hookFn = hooks[event.hookName];
-				if (!hookFn) return {
-					eventId: event.id,
-					status: "failed",
-					error: `Hook '${event.hookName}' not found in hooks map`,
-					attempts: event.attempts,
-					maxAttempts: event.maxAttempts
-				};
-				try {
-					const hookContext = { nonce: event.nonce };
-					await hookFn.call(hookContext, event.payload);
-					return {
-						eventId: event.id,
-						status: "completed"
-					};
-				} catch (error) {
-					const errorMessage = error instanceof Error ? error.message : String(error);
-					return {
-						eventId: event.id,
-						status: "failed",
-						error: errorMessage,
-						attempts: event.attempts,
-						maxAttempts: event.maxAttempts
-					};
-				}
-			}));
+		await this.handlerTx().withServiceCalls(() => {
+			const txResults = [];
 			for (const processedEvent of processedEvents) {
 				if (processedEvent.status === "rejected") continue;
 				const { eventId, status } = processedEvent.value;
-				if (status === "completed") internalFragment.services.hookService.markHookCompleted(eventId);
+				if (status === "completed") txResults.push(internalFragment.services.hookService.markHookCompleted(eventId));
 				else if (status === "failed") {
 					const { error, attempts } = processedEvent.value;
-					internalFragment.services.hookService.markHookFailed(eventId, error, attempts, retryPolicy);
+					txResults.push(internalFragment.services.hookService.markHookFailed(eventId, error, attempts, retryPolicy));
 				}
 			}
-			await executeMutate();
-		});
+			return txResults;
+		}).execute();
 	});
 }
 

package/dist/hooks/hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.js","names":["hookContext: HookContext"],"sources":["../../src/hooks/hooks.ts"],"sourcesContent":["import type { RetryPolicy } from \"../query/unit-of-work/retry-policy\";\nimport { ExponentialBackoffRetryPolicy } from \"../query/unit-of-work/retry-policy\";\nimport type { IUnitOfWork } from \"../query/unit-of-work/unit-of-work\";\nimport type { InternalFragmentInstance } from \"../fragments/internal-fragment\";\n\n/**\n * Context available in hook functions via `this`.\n * Contains the nonce for idempotency and database access.\n */\nexport interface HookContext {\n  /**\n   * Unique nonce for this transaction.\n   * Use this for idempotency checks in your hook implementation.\n   */\n  nonce: string;\n}\n\n/**\n * A hook function signature.\n * Hooks receive a typed payload and access context via `this`.\n */\nexport type HookFn<TPayload = unknown> = (payload: TPayload) => void | Promise<void>;\n\n/**\n * Map of hook names to hook functions.\n * Used for type-safe hook definitions and triggering.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type HooksMap = Record<string, HookFn<any>>;\n\n/**\n * Extract the payload type from a hook function.\n */\nexport type HookPayload<T> = T extends HookFn<infer P> ? P : never;\n\n/**\n * Options for triggering a hook.\n */\nexport interface TriggerHookOptions {\n  /**\n   * Optional retry policy override for this specific hook trigger.\n   * If not provided, uses the default retry policy.\n   */\n  retryPolicy?: RetryPolicy;\n}\n\n/**\n * Internal representation of a triggered hook.\n * Stored in the Unit of Work before execution.\n */\nexport interface TriggeredHook {\n  hookName: string;\n  payload: unknown;\n  options?: TriggerHookOptions;\n}\n\n/**\n * Configuration for hook processing.\n */\nexport interface HookProcessorConfig {\n  hooks: HooksMap;\n  namespace: string;\n  internalFragment: InternalFragmentInstance;\n  defaultRetryPolicy?: RetryPolicy;\n}\n\n/**\n * Add hook events as mutation operations to the UOW.\n * This should be called before executeMutations() so hook records are created\n * in the same transaction as the user's mutations.\n */\nexport function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConfig): void {\n  const { namespace, internalFragment, defaultRetryPolicy } = config;\n  const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });\n\n  const triggeredHooks = uow.getTriggeredHooks();\n\n  if (triggeredHooks.length === 0) {\n    return;\n  }\n\n  const internalSchema = internalFragment.$internal.deps.schema;\n  const internalUow = uow.forSchema(internalSchema);\n\n  for (const hook of triggeredHooks) {\n    const hookRetryPolicy = hook.options?.retryPolicy ?? retryPolicy;\n    const maxAttempts = hookRetryPolicy.shouldRetry(4) ? 5 : 1;\n    internalUow.create(\"fragno_hooks\", {\n      namespace,\n      hookName: hook.hookName,\n      payload: hook.payload,\n      status: \"pending\",\n      attempts: 0,\n      maxAttempts,\n      lastAttemptAt: null,\n      nextRetryAt: null,\n      error: null,\n      nonce: uow.nonce,\n    });\n  }\n}\n\n/**\n * Process pending hook events after the transaction has committed.\n * This should be called in the onSuccess callback after executeMutations().\n */\nexport async function processHooks(config: HookProcessorConfig): Promise<void> {\n  const { hooks, namespace, internalFragment, defaultRetryPolicy } = config;\n  const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });\n\n  await internalFragment.inContext(async function () {\n    return await this.uow(async ({ executeRetrieve, executeMutate }) => {\n      const pendingEventsPromise =\n        internalFragment.services.hookService.getPendingHookEvents(namespace);\n      await executeRetrieve();\n\n      const pendingEvents = await pendingEventsPromise;\n\n      if (pendingEvents.length === 0) {\n        return;\n      }\n\n      const processedEvents = await Promise.allSettled(\n        pendingEvents.map(async (event) => {\n          const hookFn = hooks[event.hookName];\n          if (!hookFn) {\n            return {\n              eventId: event.id,\n              status: \"failed\" as const,\n              error: `Hook '${event.hookName}' not found in hooks map`,\n              attempts: event.attempts,\n              maxAttempts: event.maxAttempts,\n            };\n          }\n\n          try {\n            const hookContext: HookContext = { nonce: event.nonce };\n            await hookFn.call(hookContext, event.payload);\n            return {\n              eventId: event.id,\n              status: \"completed\" as const,\n            };\n          } catch (error) {\n            const errorMessage = error instanceof Error ? error.message : String(error);\n            return {\n              eventId: event.id,\n              status: \"failed\" as const,\n              error: errorMessage,\n              attempts: event.attempts,\n              maxAttempts: event.maxAttempts,\n            };\n          }\n        }),\n      );\n\n      for (const processedEvent of processedEvents) {\n        if (processedEvent.status === \"rejected\") {\n          continue;\n        }\n\n        const { eventId, status } = processedEvent.value;\n\n        if (status === \"completed\") {\n          internalFragment.services.hookService.markHookCompleted(eventId);\n        } else if (status === \"failed\") {\n          const { error, attempts } = processedEvent.value;\n          internalFragment.services.hookService.markHookFailed(\n            eventId,\n            error,\n            attempts,\n            retryPolicy,\n          );\n        }\n      }\n\n      await executeMutate();\n    });\n  });\n}\n"],"mappings":";;;;;;;;AAuEA,SAAgB,qBAAqB,KAAkB,QAAmC;CACxF,MAAM,EAAE,WAAW,kBAAkB,uBAAuB;CAC5D,MAAM,cAAc,sBAAsB,IAAI,8BAA8B,EAAE,YAAY,GAAG,CAAC;CAE9F,MAAM,iBAAiB,IAAI,mBAAmB;AAE9C,KAAI,eAAe,WAAW,EAC5B;CAGF,MAAM,iBAAiB,iBAAiB,UAAU,KAAK;CACvD,MAAM,cAAc,IAAI,UAAU,eAAe;AAEjD,MAAK,MAAM,QAAQ,gBAAgB;EAEjC,MAAM,eADkB,KAAK,SAAS,eAAe,aACjB,YAAY,EAAE,GAAG,IAAI;AACzD,cAAY,OAAO,gBAAgB;GACjC;GACA,UAAU,KAAK;GACf,SAAS,KAAK;GACd,QAAQ;GACR,UAAU;GACV;GACA,eAAe;GACf,aAAa;GACb,OAAO;GACP,OAAO,IAAI;GACZ,CAAC;;;;;;;AAQN,eAAsB,aAAa,QAA4C;CAC7E,MAAM,EAAE,OAAO,WAAW,kBAAkB,uBAAuB;CACnE,MAAM,cAAc,sBAAsB,IAAI,8BAA8B,EAAE,YAAY,GAAG,CAAC;AAE9F,OAAM,iBAAiB,UAAU,iBAAkB;AACjD,SAAO,MAAM,KAAK,IAAI,OAAO,EAAE,iBAAiB,oBAAoB;GAClE,MAAM,uBACJ,iBAAiB,SAAS,YAAY,qBAAqB,UAAU;AACvE,SAAM,iBAAiB;GAEvB,MAAM,gBAAgB,MAAM;AAE5B,OAAI,cAAc,WAAW,EAC3B;GAGF,MAAM,kBAAkB,MAAM,QAAQ,WACpC,cAAc,IAAI,OAAO,UAAU;IACjC,MAAM,SAAS,MAAM,MAAM;AAC3B,QAAI,CAAC,OACH,QAAO;KACL,SAAS,MAAM;KACf,QAAQ;KACR,OAAO,SAAS,MAAM,SAAS;KAC/B,UAAU,MAAM;KAChB,aAAa,MAAM;KACpB;AAGH,QAAI;KACF,MAAMA,cAA2B,EAAE,OAAO,MAAM,OAAO;AACvD,WAAM,OAAO,KAAK,aAAa,MAAM,QAAQ;AAC7C,YAAO;MACL,SAAS,MAAM;MACf,QAAQ;MACT;aACM,OAAO;KACd,MAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AAC3E,YAAO;MACL,SAAS,MAAM;MACf,QAAQ;MACR,OAAO;MACP,UAAU,MAAM;MAChB,aAAa,MAAM;MACpB;;KAEH,CACH;AAED,QAAK,MAAM,kBAAkB,iBAAiB;AAC5C,QAAI,eAAe,WAAW,WAC5B;IAGF,MAAM,EAAE,SAAS,WAAW,eAAe;AAE3C,QAAI,WAAW,YACb,kBAAiB,SAAS,YAAY,kBAAkB,QAAQ;aACvD,WAAW,UAAU;KAC9B,MAAM,EAAE,OAAO,aAAa,eAAe;AAC3C,sBAAiB,SAAS,YAAY,eACpC,SACA,OACA,UACA,YACD;;;AAIL,SAAM,eAAe;IACrB;GACF"}
+{"version":3,"file":"hooks.js","names":["hookContext: HookContext","txResults: TxResult<void>[]"],"sources":["../../src/hooks/hooks.ts"],"sourcesContent":["import type { RetryPolicy } from \"../query/unit-of-work/retry-policy\";\nimport { ExponentialBackoffRetryPolicy } from \"../query/unit-of-work/retry-policy\";\nimport type { IUnitOfWork } from \"../query/unit-of-work/unit-of-work\";\nimport type { InternalFragmentInstance } from \"../fragments/internal-fragment\";\nimport type { TxResult } from \"../query/unit-of-work/execute-unit-of-work\";\n\n/**\n * Context available in hook functions via `this`.\n * Contains the idempotency key for idempotency and database access.\n */\nexport interface HookContext {\n  /**\n   * Unique idempotency key for this transaction.\n   * Use this for idempotency checks in your hook implementation.\n   */\n  idempotencyKey: string;\n}\n\n/**\n * A hook function signature.\n * Hooks receive a typed payload and access context via `this`.\n */\nexport type HookFn<TPayload = unknown> = (payload: TPayload) => void | Promise<void>;\n\n/**\n * Map of hook names to hook functions.\n * Used for type-safe hook definitions and triggering.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type HooksMap = Record<string, HookFn<any>>;\n\n/**\n * Extract the payload type from a hook function.\n */\nexport type HookPayload<T> = T extends HookFn<infer P> ? P : never;\n\n/**\n * Options for triggering a hook.\n */\nexport interface TriggerHookOptions {\n  /**\n   * Optional retry policy override for this specific hook trigger.\n   * If not provided, uses the default retry policy.\n   */\n  retryPolicy?: RetryPolicy;\n}\n\n/**\n * Internal representation of a triggered hook.\n * Stored in the Unit of Work before execution.\n */\nexport interface TriggeredHook {\n  hookName: string;\n  payload: unknown;\n  options?: TriggerHookOptions;\n}\n\n/**\n * Configuration for hook processing.\n */\nexport interface HookProcessorConfig {\n  hooks: HooksMap;\n  namespace: string;\n  internalFragment: InternalFragmentInstance;\n  defaultRetryPolicy?: RetryPolicy;\n}\n\n/**\n * Add hook events as mutation operations to the UOW.\n * This should be called before executeMutations() so hook records are created\n * in the same transaction as the user's mutations.\n */\nexport function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConfig): void {\n  const { namespace, internalFragment, defaultRetryPolicy } = config;\n  const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });\n\n  const triggeredHooks = uow.getTriggeredHooks();\n\n  if (triggeredHooks.length === 0) {\n    return;\n  }\n\n  const internalSchema = internalFragment.$internal.deps.schema;\n  const internalUow = uow.forSchema(internalSchema);\n\n  for (const hook of triggeredHooks) {\n    const hookRetryPolicy = hook.options?.retryPolicy ?? retryPolicy;\n    const maxAttempts = hookRetryPolicy.shouldRetry(4) ? 5 : 1;\n    internalUow.create(\"fragno_hooks\", {\n      namespace,\n      hookName: hook.hookName,\n      payload: hook.payload,\n      status: \"pending\",\n      attempts: 0,\n      maxAttempts,\n      lastAttemptAt: null,\n      nextRetryAt: null,\n      error: null,\n      nonce: uow.idempotencyKey,\n    });\n  }\n}\n\n/**\n * Process pending hook events after the transaction has committed.\n * This should be called in the onSuccess callback after executeMutations().\n */\nexport async function processHooks(config: HookProcessorConfig): Promise<void> {\n  const { hooks, namespace, internalFragment, defaultRetryPolicy } = config;\n  const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });\n\n  // Get pending events\n  const pendingEvents = await internalFragment.inContext(async function () {\n    return await this.handlerTx()\n      .withServiceCalls(\n        () => [internalFragment.services.hookService.getPendingHookEvents(namespace)] as const,\n      )\n      .transform(({ serviceResult: [events] }) => events)\n      .execute();\n  });\n\n  if (pendingEvents.length === 0) {\n    return;\n  }\n\n  // Process events (async work outside transaction)\n  const processedEvents = await Promise.allSettled(\n    pendingEvents.map(async (event) => {\n      const hookFn = hooks[event.hookName];\n      if (!hookFn) {\n        return {\n          eventId: event.id,\n          status: \"failed\" as const,\n          error: `Hook '${event.hookName}' not found in hooks map`,\n          attempts: event.attempts,\n          maxAttempts: event.maxAttempts,\n        };\n      }\n\n      try {\n        const hookContext: HookContext = { idempotencyKey: event.idempotencyKey };\n        await hookFn.call(hookContext, event.payload);\n        return {\n          eventId: event.id,\n          status: \"completed\" as const,\n        };\n      } catch (error) {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        return {\n          eventId: event.id,\n          status: \"failed\" as const,\n          error: errorMessage,\n          attempts: event.attempts,\n          maxAttempts: event.maxAttempts,\n        };\n      }\n    }),\n  );\n\n  // Mark events as completed/failed\n  await internalFragment.inContext(async function () {\n    await this.handlerTx()\n      .withServiceCalls(() => {\n        const txResults: TxResult<void>[] = [];\n        for (const processedEvent of processedEvents) {\n          if (processedEvent.status === \"rejected\") {\n            continue;\n          }\n\n          const { eventId, status } = processedEvent.value;\n\n          if (status === \"completed\") {\n            txResults.push(internalFragment.services.hookService.markHookCompleted(eventId));\n          } else if (status === \"failed\") {\n            const { error, attempts } = processedEvent.value;\n            txResults.push(\n              internalFragment.services.hookService.markHookFailed(\n                eventId,\n                error,\n                attempts,\n                retryPolicy,\n              ),\n            );\n          }\n        }\n        return txResults;\n      })\n      .execute();\n  });\n}\n"],"mappings":";;;;;;;;AAwEA,SAAgB,qBAAqB,KAAkB,QAAmC;CACxF,MAAM,EAAE,WAAW,kBAAkB,uBAAuB;CAC5D,MAAM,cAAc,sBAAsB,IAAI,8BAA8B,EAAE,YAAY,GAAG,CAAC;CAE9F,MAAM,iBAAiB,IAAI,mBAAmB;AAE9C,KAAI,eAAe,WAAW,EAC5B;CAGF,MAAM,iBAAiB,iBAAiB,UAAU,KAAK;CACvD,MAAM,cAAc,IAAI,UAAU,eAAe;AAEjD,MAAK,MAAM,QAAQ,gBAAgB;EAEjC,MAAM,eADkB,KAAK,SAAS,eAAe,aACjB,YAAY,EAAE,GAAG,IAAI;AACzD,cAAY,OAAO,gBAAgB;GACjC;GACA,UAAU,KAAK;GACf,SAAS,KAAK;GACd,QAAQ;GACR,UAAU;GACV;GACA,eAAe;GACf,aAAa;GACb,OAAO;GACP,OAAO,IAAI;GACZ,CAAC;;;;;;;AAQN,eAAsB,aAAa,QAA4C;CAC7E,MAAM,EAAE,OAAO,WAAW,kBAAkB,uBAAuB;CACnE,MAAM,cAAc,sBAAsB,IAAI,8BAA8B,EAAE,YAAY,GAAG,CAAC;CAG9F,MAAM,gBAAgB,MAAM,iBAAiB,UAAU,iBAAkB;AACvE,SAAO,MAAM,KAAK,WAAW,CAC1B,uBACO,CAAC,iBAAiB,SAAS,YAAY,qBAAqB,UAAU,CAAC,CAC9E,CACA,WAAW,EAAE,eAAe,CAAC,cAAc,OAAO,CAClD,SAAS;GACZ;AAEF,KAAI,cAAc,WAAW,EAC3B;CAIF,MAAM,kBAAkB,MAAM,QAAQ,WACpC,cAAc,IAAI,OAAO,UAAU;EACjC,MAAM,SAAS,MAAM,MAAM;AAC3B,MAAI,CAAC,OACH,QAAO;GACL,SAAS,MAAM;GACf,QAAQ;GACR,OAAO,SAAS,MAAM,SAAS;GAC/B,UAAU,MAAM;GAChB,aAAa,MAAM;GACpB;AAGH,MAAI;GACF,MAAMA,cAA2B,EAAE,gBAAgB,MAAM,gBAAgB;AACzE,SAAM,OAAO,KAAK,aAAa,MAAM,QAAQ;AAC7C,UAAO;IACL,SAAS,MAAM;IACf,QAAQ;IACT;WACM,OAAO;GACd,MAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AAC3E,UAAO;IACL,SAAS,MAAM;IACf,QAAQ;IACR,OAAO;IACP,UAAU,MAAM;IAChB,aAAa,MAAM;IACpB;;GAEH,CACH;AAGD,OAAM,iBAAiB,UAAU,iBAAkB;AACjD,QAAM,KAAK,WAAW,CACnB,uBAAuB;GACtB,MAAMC,YAA8B,EAAE;AACtC,QAAK,MAAM,kBAAkB,iBAAiB;AAC5C,QAAI,eAAe,WAAW,WAC5B;IAGF,MAAM,EAAE,SAAS,WAAW,eAAe;AAE3C,QAAI,WAAW,YACb,WAAU,KAAK,iBAAiB,SAAS,YAAY,kBAAkB,QAAQ,CAAC;aACvE,WAAW,UAAU;KAC9B,MAAM,EAAE,OAAO,aAAa,eAAe;AAC3C,eAAU,KACR,iBAAiB,SAAS,YAAY,eACpC,SACA,OACA,UACA,YACD,CACF;;;AAGL,UAAO;IACP,CACD,SAAS;GACZ"}

package/dist/mod.d.ts

@@ -1,13 +1,13 @@
 import { AnySchema } from "./schema/create.js";
 import { Cursor, CursorData, CursorResult, decodeCursor } from "./query/cursor.js";
 import { ExponentialBackoffRetryPolicy, LinearBackoffRetryPolicy, NoRetryPolicy, RetryPolicy } from "./query/unit-of-work/retry-policy.js";
-import { ExecuteUnitOfWorkCallbacks, ExecuteUnitOfWorkOptions, ExecuteUnitOfWorkResult, executeUnitOfWork } from "./query/unit-of-work/execute-unit-of-work.js";
+import { BuilderTransformContextWithMutate, BuilderTransformContextWithoutMutate, ConcurrencyConflictError, ExtractServiceFinalResults, ExtractServiceRetrieveResults, HandlerBuilderMutateContext, HandlerTxBuilder, ServiceBuilderMutateContext, ServiceTxBuilder, TxResult, createHandlerTxBuilder, createServiceTxBuilder } from "./query/unit-of-work/execute-unit-of-work.js";
 import { DatabaseFragmentContext, DatabaseFragmentDefinitionBuilder, DatabaseHandlerContext, FragnoPublicConfigWithDatabase, ImplicitDatabaseDependencies } from "./db-fragment-definition-builder.js";
+import { withDatabase } from "./with-database.js";
 import { InternalFragmentInstance, internalFragmentDef } from "./fragments/internal-fragment.js";
 import { HookContext, HookFn, HookPayload, HooksMap, TriggerHookOptions } from "./hooks/hooks.js";
 import { IUnitOfWork, IUnitOfWorkRestricted, TypedUnitOfWork, UOWCompiler, UOWDecoder, UOWExecutor, UnitOfWork, createUnitOfWork } from "./query/unit-of-work/unit-of-work.js";
 import { DatabaseAdapter } from "./adapters/adapters.js";
-import { withDatabase } from "./with-database.js";
 import { AnyFragnoInstantiatedFragment, BoundServices, FragnoInstantiatedFragment } from "@fragno-dev/core";
 
 //#region src/mod.d.ts
@@ -61,5 +61,5 @@ type AnyFragnoInstantiatedDatabaseFragment = FragnoInstantiatedFragment<any, Imp
  */
 declare function migrate(fragment: AnyFragnoInstantiatedDatabaseFragment): Promise<void>;
 //#endregion
-export { AnyFragnoInstantiatedDatabaseFragment, type BoundServices, CreateFragnoDatabaseDefinitionOptions, Cursor, type CursorData, type CursorResult, type DatabaseAdapter, type DatabaseFragmentContext, DatabaseFragmentDefinitionBuilder, type DatabaseHandlerContext as DatabaseRequestContext, type ExecuteUnitOfWorkCallbacks, type ExecuteUnitOfWorkOptions, type ExecuteUnitOfWorkResult, ExponentialBackoffRetryPolicy, FragnoDatabase, type FragnoPublicConfigWithDatabase, type HookContext, type HookFn, type HookPayload, type HooksMap, type IUnitOfWork, type IUnitOfWorkRestricted, type ImplicitDatabaseDependencies, type InternalFragmentInstance, LinearBackoffRetryPolicy, NoRetryPolicy, type RetryPolicy, type TriggerHookOptions, TypedUnitOfWork, type UOWCompiler, type UOWDecoder, type UOWExecutor, UnitOfWork, createUnitOfWork, decodeCursor, executeUnitOfWork, fragnoDatabaseFakeSymbol, fragnoDatabaseLibraryVersion, internalFragmentDef, isFragnoDatabase, migrate, withDatabase };
+export { AnyFragnoInstantiatedDatabaseFragment, type BoundServices, type BuilderTransformContextWithMutate, type BuilderTransformContextWithoutMutate, ConcurrencyConflictError, CreateFragnoDatabaseDefinitionOptions, Cursor, type CursorData, type CursorResult, type DatabaseAdapter, type DatabaseFragmentContext, DatabaseFragmentDefinitionBuilder, type DatabaseHandlerContext as DatabaseRequestContext, ExponentialBackoffRetryPolicy, type ExtractServiceFinalResults, type ExtractServiceRetrieveResults, FragnoDatabase, type FragnoPublicConfigWithDatabase, type HandlerBuilderMutateContext, HandlerTxBuilder, type HookContext, type HookFn, type HookPayload, type HooksMap, type IUnitOfWork, type IUnitOfWorkRestricted, type ImplicitDatabaseDependencies, type InternalFragmentInstance, LinearBackoffRetryPolicy, NoRetryPolicy, type RetryPolicy, type ServiceBuilderMutateContext, ServiceTxBuilder, type TriggerHookOptions, type TxResult, TypedUnitOfWork, type UOWCompiler, type UOWDecoder, type UOWExecutor, UnitOfWork, createHandlerTxBuilder, createServiceTxBuilder, createUnitOfWork, decodeCursor, fragnoDatabaseFakeSymbol, fragnoDatabaseLibraryVersion, internalFragmentDef, isFragnoDatabase, migrate, withDatabase };
 //# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;cAiBa;cACA;UAEI,gDAAgD;;EAHpD,MAAA,EAKH,CALG;AACb;AAEiB,iBAKD,gBAAA,CALC,KAAqC,EAAA,OAAA,CAAW,EAAA,KAAA,IAKN,cAHhD,CAG+D,SAH/D,CAAA;AAGX;AAmBA;;;AAKgF,cALnE,cAKmE,CAAA,gBALpC,SAKoC,EAAA,aAAA,IAAA,CAAA,CAAA;EAAhB,CAAA,OAAA;EAMrB,WAAA,CAAA,OAAA,EAAA;IAApC,SAAA,EAAA,MAAA;IAQK,MAAA,EAdwC,CAcxC;IAIqB,OAAA,EAlB+B,eAkB/B,CAlB+C,UAkB/C,CAAA;EAAhB,CAAA;EAAe,KAZzB,wBAAA,GAYyB,EAAA,OAZW,wBAYX;EAiDpB,IAAA,SAAA,CAAA,CAAA,EAAA,MAAA;EAGmB,IAAA,MAAA,CAAA,CAAA,EAxDnB,CAwDmB;EAA7B,IAAA,OAAA,CAAA,CAAA,EApDe,eAoDf,CApD+B,UAoD/B,CAAA;;KAHU,qCAAA,GAAwC,gCAGlD,6BAA6B,gCAS7B;oBAEoB;IAA6B,eAAe;;;;;;;;;;;;;;;;;;;;;;;iBAyB5C,OAAA,WAAkB,wCAAwC"}
+{"version":3,"file":"mod.d.ts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;cAiBa;cACA;UAEI,gDAAgD;;EAHpD,MAAA,EAKH,CALG;AACb;AAEiB,iBAKD,gBAAA,CALC,KAAqC,EAAA,OAAA,CAAW,EAAA,KAAA,IAKN,cAHhD,CAG+D,SAH/D,CAAA;AAGX;AAmBA;;;AAKgF,cALnE,cAKmE,CAAA,gBALpC,SAKoC,EAAA,aAAA,IAAA,CAAA,CAAA;EAAhB,CAAA,OAAA;EAMrB,WAAA,CAAA,OAAA,EAAA;IAApC,SAAA,EAAA,MAAA;IAQK,MAAA,EAdwC,CAcxC;IAIqB,OAAA,EAlB+B,eAkB/B,CAlB+C,UAkB/C,CAAA;EAAhB,CAAA;EAAe,KAZzB,wBAAA,GAYyB,EAAA,OAZW,wBAYX;EA2DpB,IAAA,SAAA,CAAA,CAAA,EAAA,MAAA;EAGmB,IAAA,MAAA,CAAA,CAAA,EAlEnB,CAkEmB;EAA7B,IAAA,OAAA,CAAA,CAAA,EA9De,eA8Df,CA9D+B,UA8D/B,CAAA;;KAHU,qCAAA,GAAwC,gCAGlD,6BAA6B,gCAS7B;oBAEoB;IAA6B,eAAe;;;;;;;;;;;;;;;;;;;;;;;iBAyB5C,OAAA,WAAkB,wCAAwC"}

package/dist/mod.js

@@ -1,10 +1,10 @@
-import { Cursor, decodeCursor } from "./query/cursor.js";
-import { TypedUnitOfWork, UnitOfWork, createUnitOfWork } from "./query/unit-of-work/unit-of-work.js";
 import { ExponentialBackoffRetryPolicy, LinearBackoffRetryPolicy, NoRetryPolicy } from "./query/unit-of-work/retry-policy.js";
-import { executeUnitOfWork } from "./query/unit-of-work/execute-unit-of-work.js";
+import { ConcurrencyConflictError, HandlerTxBuilder, ServiceTxBuilder, createHandlerTxBuilder, createServiceTxBuilder } from "./query/unit-of-work/execute-unit-of-work.js";
 import { DatabaseFragmentDefinitionBuilder } from "./db-fragment-definition-builder.js";
+import { Cursor, decodeCursor } from "./query/cursor.js";
 import { getSchemaVersionFromDatabase, internalFragmentDef } from "./fragments/internal-fragment.js";
 import { withDatabase } from "./with-database.js";
+import { TypedUnitOfWork, UnitOfWork, createUnitOfWork } from "./query/unit-of-work/unit-of-work.js";
 
 //#region src/mod.ts
 const fragnoDatabaseFakeSymbol = "$fragno-database";
@@ -84,5 +84,5 @@ async function migrate(fragment) {
 }
 
 //#endregion
-export { Cursor, DatabaseFragmentDefinitionBuilder, ExponentialBackoffRetryPolicy, FragnoDatabase, LinearBackoffRetryPolicy, NoRetryPolicy, TypedUnitOfWork, UnitOfWork, createUnitOfWork, decodeCursor, executeUnitOfWork, fragnoDatabaseFakeSymbol, fragnoDatabaseLibraryVersion, internalFragmentDef, isFragnoDatabase, migrate, withDatabase };
+export { ConcurrencyConflictError, Cursor, DatabaseFragmentDefinitionBuilder, ExponentialBackoffRetryPolicy, FragnoDatabase, HandlerTxBuilder, LinearBackoffRetryPolicy, NoRetryPolicy, ServiceTxBuilder, TypedUnitOfWork, UnitOfWork, createHandlerTxBuilder, createServiceTxBuilder, createUnitOfWork, decodeCursor, fragnoDatabaseFakeSymbol, fragnoDatabaseLibraryVersion, internalFragmentDef, isFragnoDatabase, migrate, withDatabase };
 //# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -1 +1 @@
-{"version":3,"file":"mod.js","names":["#namespace","#schema","#adapter"],"sources":["../src/mod.ts"],"sourcesContent":["import type { DatabaseAdapter } from \"./adapters/adapters\";\nimport type { AnySchema } from \"./schema/create\";\nimport type { CursorResult } from \"./query/cursor\";\nimport { Cursor } from \"./query/cursor\";\nimport type { FragnoInstantiatedFragment, AnyFragnoInstantiatedFragment } from \"@fragno-dev/core\";\nimport type {\n  FragnoPublicConfigWithDatabase,\n  ImplicitDatabaseDependencies,\n} from \"./db-fragment-definition-builder\";\nimport {\n  getSchemaVersionFromDatabase,\n  type InternalFragmentInstance,\n} from \"./fragments/internal-fragment\";\n\nexport type { DatabaseAdapter, CursorResult };\nexport { Cursor };\n\nexport const fragnoDatabaseFakeSymbol = \"$fragno-database\" as const;\nexport const fragnoDatabaseLibraryVersion = \"0.1\" as const;\n\nexport interface CreateFragnoDatabaseDefinitionOptions<T extends AnySchema> {\n  namespace: string;\n  schema: T;\n}\n\nexport function isFragnoDatabase(value: unknown): value is FragnoDatabase<AnySchema> {\n  if (value instanceof FragnoDatabase) {\n    return true;\n  }\n\n  if (typeof value !== \"object\" || value === null) {\n    return false;\n  }\n\n  return (\n    fragnoDatabaseFakeSymbol in value &&\n    value[fragnoDatabaseFakeSymbol] === fragnoDatabaseFakeSymbol\n  );\n}\n\n/**\n * A Fragno database instance with a bound adapter.\n * Created from a FragnoDatabaseDefinition by calling .create(adapter).\n */\nexport class FragnoDatabase<const T extends AnySchema, TUOWConfig = void> {\n  #namespace: string;\n  #schema: T;\n  #adapter: DatabaseAdapter<TUOWConfig>;\n\n  constructor(options: { namespace: string; schema: T; adapter: DatabaseAdapter<TUOWConfig> }) {\n    this.#namespace = options.namespace;\n    this.#schema = options.schema;\n    this.#adapter = options.adapter;\n  }\n\n  get [fragnoDatabaseFakeSymbol](): typeof fragnoDatabaseFakeSymbol {\n    return fragnoDatabaseFakeSymbol;\n  }\n\n  get namespace() {\n    return this.#namespace;\n  }\n\n  get schema() {\n    return this.#schema;\n  }\n\n  get adapter(): DatabaseAdapter<TUOWConfig> {\n    return this.#adapter;\n  }\n}\n\nexport {\n  DatabaseFragmentDefinitionBuilder,\n  type FragnoPublicConfigWithDatabase,\n  type DatabaseFragmentContext,\n  type DatabaseHandlerContext as DatabaseRequestContext,\n  type ImplicitDatabaseDependencies,\n} from \"./db-fragment-definition-builder\";\n\nexport { withDatabase } from \"./with-database\";\n\nexport { decodeCursor, type CursorData } from \"./query/cursor\";\n\nexport {\n  createUnitOfWork,\n  UnitOfWork,\n  TypedUnitOfWork,\n  type IUnitOfWork,\n  type IUnitOfWorkRestricted,\n  type UOWCompiler,\n  type UOWExecutor,\n  type UOWDecoder,\n} from \"./query/unit-of-work/unit-of-work\";\n\nexport {\n  type RetryPolicy,\n  NoRetryPolicy,\n  ExponentialBackoffRetryPolicy,\n  LinearBackoffRetryPolicy,\n} from \"./query/unit-of-work/retry-policy\";\n\nexport {\n  executeUnitOfWork,\n  type ExecuteUnitOfWorkResult,\n  type ExecuteUnitOfWorkCallbacks,\n  type ExecuteUnitOfWorkOptions,\n} from \"./query/unit-of-work/execute-unit-of-work\";\n\nexport type { BoundServices } from \"@fragno-dev/core\";\n\nexport { internalFragmentDef } from \"./fragments/internal-fragment\";\nexport type { InternalFragmentInstance } from \"./fragments/internal-fragment\";\n\nexport type { HookContext, HooksMap, HookFn, HookPayload, TriggerHookOptions } from \"./hooks/hooks\";\n\nexport type AnyFragnoInstantiatedDatabaseFragment = FragnoInstantiatedFragment<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  ImplicitDatabaseDependencies<AnySchema>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  FragnoPublicConfigWithDatabase,\n  // Ensure the fragment has the internal fragment linked\n  { _fragno_internal: InternalFragmentInstance } & Record<string, AnyFragnoInstantiatedFragment>\n>;\n\n/**\n * Helper function to run migrations for a database fragment.\n * Extracts the database adapter, schema, and namespace from the fragment and runs migrations.\n * This function:\n * 1. Ensures the internal settings fragment is migrated first\n * 2. Retrieves the current database version from the internal fragment\n * 3. Runs migration from current version to target version\n *\n * @param fragment - The instantiated fragment to run migrations for\n * @throws Error if the fragment doesn't have database support or the adapter doesn't support migrations\n *\n * @example\n * ```typescript\n * const fragment = instantiate(myFragmentDef)\n *   .withConfig({})\n *   .withRoutes([])\n *   .withOptions({ databaseAdapter: myAdapter })\n *   .build();\n *\n * await migrate(fragment);\n * ```\n */\nexport async function migrate(fragment: AnyFragnoInstantiatedDatabaseFragment): Promise<void> {\n  const { options, deps, linkedFragments } = fragment.$internal;\n  const adapter = options.databaseAdapter;\n\n  // Check if adapter supports prepareMigrations\n  if (!adapter.prepareMigrations) {\n    throw new Error(\n      \"Database adapter does not support prepareMigrations. Please use an adapter that implements this method.\",\n    );\n  }\n\n  const schema = deps.schema;\n  const namespace = deps.namespace;\n\n  // Step 1: Ensure the internal fragment (settings table) is migrated first\n  const internalFragment = linkedFragments._fragno_internal;\n\n  if (!internalFragment) {\n    throw new Error(\"Internal fragment not found. Please ensure the internal fragment is linked.\");\n  }\n\n  if (!(await adapter.isConnectionHealthy())) {\n    throw new Error(\n      \"Database connection is not healthy. Please check your database connection and try again.\",\n    );\n  }\n\n  const internalDeps = internalFragment.$internal.deps;\n  const internalSchema = internalDeps.schema;\n  const internalNamespace = internalDeps.namespace;\n\n  const internalCurrentVersion = await getSchemaVersionFromDatabase(\n    internalFragment,\n    internalNamespace,\n  );\n\n  // Migrate internal fragment if needed\n  if (internalCurrentVersion < internalSchema.version) {\n    const internalMigrations = adapter.prepareMigrations(internalSchema, internalNamespace);\n    await internalMigrations.execute(internalCurrentVersion, internalSchema.version);\n  }\n\n  // Step 2: Get current database version for this fragment's namespace\n  const currentVersion = await getSchemaVersionFromDatabase(internalFragment, namespace);\n\n  // Step 3: Run the migration from current version to target version\n  const targetVersion = schema.version;\n\n  if (currentVersion === targetVersion) {\n    return;\n  }\n\n  if (currentVersion > targetVersion) {\n    throw new Error(\n      `Cannot migrate backwards: current version (${currentVersion}) > target version (${targetVersion})`,\n    );\n  }\n\n  const migrations = adapter.prepareMigrations(schema, namespace);\n  await migrations.execute(currentVersion, targetVersion);\n}\n"],"mappings":";;;;;;;;;AAiBA,MAAa,2BAA2B;AACxC,MAAa,+BAA+B;AAO5C,SAAgB,iBAAiB,OAAoD;AACnF,KAAI,iBAAiB,eACnB,QAAO;AAGT,KAAI,OAAO,UAAU,YAAY,UAAU,KACzC,QAAO;AAGT,QACE,4BAA4B,SAC5B,MAAM,8BAA8B;;;;;;AAQxC,IAAa,iBAAb,MAA0E;CACxE;CACA;CACA;CAEA,YAAY,SAAiF;AAC3F,QAAKA,YAAa,QAAQ;AAC1B,QAAKC,SAAU,QAAQ;AACvB,QAAKC,UAAW,QAAQ;;CAG1B,KAAK,4BAA6D;AAChE,SAAO;;CAGT,IAAI,YAAY;AACd,SAAO,MAAKF;;CAGd,IAAI,SAAS;AACX,SAAO,MAAKC;;CAGd,IAAI,UAAuC;AACzC,SAAO,MAAKC;;;;;;;;;;;;;;;;;;;;;;;;;AAuFhB,eAAsB,QAAQ,UAAgE;CAC5F,MAAM,EAAE,SAAS,MAAM,oBAAoB,SAAS;CACpD,MAAM,UAAU,QAAQ;AAGxB,KAAI,CAAC,QAAQ,kBACX,OAAM,IAAI,MACR,0GACD;CAGH,MAAM,SAAS,KAAK;CACpB,MAAM,YAAY,KAAK;CAGvB,MAAM,mBAAmB,gBAAgB;AAEzC,KAAI,CAAC,iBACH,OAAM,IAAI,MAAM,8EAA8E;AAGhG,KAAI,CAAE,MAAM,QAAQ,qBAAqB,CACvC,OAAM,IAAI,MACR,2FACD;CAGH,MAAM,eAAe,iBAAiB,UAAU;CAChD,MAAM,iBAAiB,aAAa;CACpC,MAAM,oBAAoB,aAAa;CAEvC,MAAM,yBAAyB,MAAM,6BACnC,kBACA,kBACD;AAGD,KAAI,yBAAyB,eAAe,QAE1C,OAD2B,QAAQ,kBAAkB,gBAAgB,kBAAkB,CAC9D,QAAQ,wBAAwB,eAAe,QAAQ;CAIlF,MAAM,iBAAiB,MAAM,6BAA6B,kBAAkB,UAAU;CAGtF,MAAM,gBAAgB,OAAO;AAE7B,KAAI,mBAAmB,cACrB;AAGF,KAAI,iBAAiB,cACnB,OAAM,IAAI,MACR,8CAA8C,eAAe,sBAAsB,cAAc,GAClG;AAIH,OADmB,QAAQ,kBAAkB,QAAQ,UAAU,CAC9C,QAAQ,gBAAgB,cAAc"}
+{"version":3,"file":"mod.js","names":["#namespace","#schema","#adapter"],"sources":["../src/mod.ts"],"sourcesContent":["import type { DatabaseAdapter } from \"./adapters/adapters\";\nimport type { AnySchema } from \"./schema/create\";\nimport type { CursorResult } from \"./query/cursor\";\nimport { Cursor } from \"./query/cursor\";\nimport type { FragnoInstantiatedFragment, AnyFragnoInstantiatedFragment } from \"@fragno-dev/core\";\nimport type {\n  FragnoPublicConfigWithDatabase,\n  ImplicitDatabaseDependencies,\n} from \"./db-fragment-definition-builder\";\nimport {\n  getSchemaVersionFromDatabase,\n  type InternalFragmentInstance,\n} from \"./fragments/internal-fragment\";\n\nexport type { DatabaseAdapter, CursorResult };\nexport { Cursor };\n\nexport const fragnoDatabaseFakeSymbol = \"$fragno-database\" as const;\nexport const fragnoDatabaseLibraryVersion = \"0.1\" as const;\n\nexport interface CreateFragnoDatabaseDefinitionOptions<T extends AnySchema> {\n  namespace: string;\n  schema: T;\n}\n\nexport function isFragnoDatabase(value: unknown): value is FragnoDatabase<AnySchema> {\n  if (value instanceof FragnoDatabase) {\n    return true;\n  }\n\n  if (typeof value !== \"object\" || value === null) {\n    return false;\n  }\n\n  return (\n    fragnoDatabaseFakeSymbol in value &&\n    value[fragnoDatabaseFakeSymbol] === fragnoDatabaseFakeSymbol\n  );\n}\n\n/**\n * A Fragno database instance with a bound adapter.\n * Created from a FragnoDatabaseDefinition by calling .create(adapter).\n */\nexport class FragnoDatabase<const T extends AnySchema, TUOWConfig = void> {\n  #namespace: string;\n  #schema: T;\n  #adapter: DatabaseAdapter<TUOWConfig>;\n\n  constructor(options: { namespace: string; schema: T; adapter: DatabaseAdapter<TUOWConfig> }) {\n    this.#namespace = options.namespace;\n    this.#schema = options.schema;\n    this.#adapter = options.adapter;\n  }\n\n  get [fragnoDatabaseFakeSymbol](): typeof fragnoDatabaseFakeSymbol {\n    return fragnoDatabaseFakeSymbol;\n  }\n\n  get namespace() {\n    return this.#namespace;\n  }\n\n  get schema() {\n    return this.#schema;\n  }\n\n  get adapter(): DatabaseAdapter<TUOWConfig> {\n    return this.#adapter;\n  }\n}\n\nexport {\n  DatabaseFragmentDefinitionBuilder,\n  type FragnoPublicConfigWithDatabase,\n  type DatabaseFragmentContext,\n  type DatabaseHandlerContext as DatabaseRequestContext,\n  type ImplicitDatabaseDependencies,\n} from \"./db-fragment-definition-builder\";\n\nexport { withDatabase } from \"./with-database\";\n\nexport { decodeCursor, type CursorData } from \"./query/cursor\";\n\nexport {\n  createUnitOfWork,\n  UnitOfWork,\n  TypedUnitOfWork,\n  type IUnitOfWork,\n  type IUnitOfWorkRestricted,\n  type UOWCompiler,\n  type UOWExecutor,\n  type UOWDecoder,\n} from \"./query/unit-of-work/unit-of-work\";\n\nexport {\n  type RetryPolicy,\n  NoRetryPolicy,\n  ExponentialBackoffRetryPolicy,\n  LinearBackoffRetryPolicy,\n} from \"./query/unit-of-work/retry-policy\";\n\nexport {\n  ConcurrencyConflictError,\n  // Builder pattern exports\n  ServiceTxBuilder,\n  HandlerTxBuilder,\n  createServiceTxBuilder,\n  createHandlerTxBuilder,\n  type TxResult,\n  // Builder context types\n  type ServiceBuilderMutateContext,\n  type HandlerBuilderMutateContext,\n  type BuilderTransformContextWithMutate,\n  type BuilderTransformContextWithoutMutate,\n  type ExtractServiceRetrieveResults,\n  type ExtractServiceFinalResults,\n} from \"./query/unit-of-work/execute-unit-of-work\";\n\nexport type { BoundServices } from \"@fragno-dev/core\";\n\nexport { internalFragmentDef } from \"./fragments/internal-fragment\";\nexport type { InternalFragmentInstance } from \"./fragments/internal-fragment\";\n\nexport type { HookContext, HooksMap, HookFn, HookPayload, TriggerHookOptions } from \"./hooks/hooks\";\n\nexport type AnyFragnoInstantiatedDatabaseFragment = FragnoInstantiatedFragment<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  ImplicitDatabaseDependencies<AnySchema>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  FragnoPublicConfigWithDatabase,\n  // Ensure the fragment has the internal fragment linked\n  { _fragno_internal: InternalFragmentInstance } & Record<string, AnyFragnoInstantiatedFragment>\n>;\n\n/**\n * Helper function to run migrations for a database fragment.\n * Extracts the database adapter, schema, and namespace from the fragment and runs migrations.\n * This function:\n * 1. Ensures the internal settings fragment is migrated first\n * 2. Retrieves the current database version from the internal fragment\n * 3. Runs migration from current version to target version\n *\n * @param fragment - The instantiated fragment to run migrations for\n * @throws Error if the fragment doesn't have database support or the adapter doesn't support migrations\n *\n * @example\n * ```typescript\n * const fragment = instantiate(myFragmentDef)\n *   .withConfig({})\n *   .withRoutes([])\n *   .withOptions({ databaseAdapter: myAdapter })\n *   .build();\n *\n * await migrate(fragment);\n * ```\n */\nexport async function migrate(fragment: AnyFragnoInstantiatedDatabaseFragment): Promise<void> {\n  const { options, deps, linkedFragments } = fragment.$internal;\n  const adapter = options.databaseAdapter;\n\n  // Check if adapter supports prepareMigrations\n  if (!adapter.prepareMigrations) {\n    throw new Error(\n      \"Database adapter does not support prepareMigrations. Please use an adapter that implements this method.\",\n    );\n  }\n\n  const schema = deps.schema;\n  const namespace = deps.namespace;\n\n  // Step 1: Ensure the internal fragment (settings table) is migrated first\n  const internalFragment = linkedFragments._fragno_internal;\n\n  if (!internalFragment) {\n    throw new Error(\"Internal fragment not found. Please ensure the internal fragment is linked.\");\n  }\n\n  if (!(await adapter.isConnectionHealthy())) {\n    throw new Error(\n      \"Database connection is not healthy. Please check your database connection and try again.\",\n    );\n  }\n\n  const internalDeps = internalFragment.$internal.deps;\n  const internalSchema = internalDeps.schema;\n  const internalNamespace = internalDeps.namespace;\n\n  const internalCurrentVersion = await getSchemaVersionFromDatabase(\n    internalFragment,\n    internalNamespace,\n  );\n\n  // Migrate internal fragment if needed\n  if (internalCurrentVersion < internalSchema.version) {\n    const internalMigrations = adapter.prepareMigrations(internalSchema, internalNamespace);\n    await internalMigrations.execute(internalCurrentVersion, internalSchema.version);\n  }\n\n  // Step 2: Get current database version for this fragment's namespace\n  const currentVersion = await getSchemaVersionFromDatabase(internalFragment, namespace);\n\n  // Step 3: Run the migration from current version to target version\n  const targetVersion = schema.version;\n\n  if (currentVersion === targetVersion) {\n    return;\n  }\n\n  if (currentVersion > targetVersion) {\n    throw new Error(\n      `Cannot migrate backwards: current version (${currentVersion}) > target version (${targetVersion})`,\n    );\n  }\n\n  const migrations = adapter.prepareMigrations(schema, namespace);\n  await migrations.execute(currentVersion, targetVersion);\n}\n"],"mappings":";;;;;;;;;AAiBA,MAAa,2BAA2B;AACxC,MAAa,+BAA+B;AAO5C,SAAgB,iBAAiB,OAAoD;AACnF,KAAI,iBAAiB,eACnB,QAAO;AAGT,KAAI,OAAO,UAAU,YAAY,UAAU,KACzC,QAAO;AAGT,QACE,4BAA4B,SAC5B,MAAM,8BAA8B;;;;;;AAQxC,IAAa,iBAAb,MAA0E;CACxE;CACA;CACA;CAEA,YAAY,SAAiF;AAC3F,QAAKA,YAAa,QAAQ;AAC1B,QAAKC,SAAU,QAAQ;AACvB,QAAKC,UAAW,QAAQ;;CAG1B,KAAK,4BAA6D;AAChE,SAAO;;CAGT,IAAI,YAAY;AACd,SAAO,MAAKF;;CAGd,IAAI,SAAS;AACX,SAAO,MAAKC;;CAGd,IAAI,UAAuC;AACzC,SAAO,MAAKC;;;;;;;;;;;;;;;;;;;;;;;;;AAiGhB,eAAsB,QAAQ,UAAgE;CAC5F,MAAM,EAAE,SAAS,MAAM,oBAAoB,SAAS;CACpD,MAAM,UAAU,QAAQ;AAGxB,KAAI,CAAC,QAAQ,kBACX,OAAM,IAAI,MACR,0GACD;CAGH,MAAM,SAAS,KAAK;CACpB,MAAM,YAAY,KAAK;CAGvB,MAAM,mBAAmB,gBAAgB;AAEzC,KAAI,CAAC,iBACH,OAAM,IAAI,MAAM,8EAA8E;AAGhG,KAAI,CAAE,MAAM,QAAQ,qBAAqB,CACvC,OAAM,IAAI,MACR,2FACD;CAGH,MAAM,eAAe,iBAAiB,UAAU;CAChD,MAAM,iBAAiB,aAAa;CACpC,MAAM,oBAAoB,aAAa;CAEvC,MAAM,yBAAyB,MAAM,6BACnC,kBACA,kBACD;AAGD,KAAI,yBAAyB,eAAe,QAE1C,OAD2B,QAAQ,kBAAkB,gBAAgB,kBAAkB,CAC9D,QAAQ,wBAAwB,eAAe,QAAQ;CAIlF,MAAM,iBAAiB,MAAM,6BAA6B,kBAAkB,UAAU;CAGtF,MAAM,gBAAgB,OAAO;AAE7B,KAAI,mBAAmB,cACrB;AAGF,KAAI,iBAAiB,cACnB,OAAM,IAAI,MACR,8CAA8C,eAAe,sBAAsB,cAAc,GAClG;AAIH,OADmB,QAAQ,kBAAkB,QAAQ,UAAU,CAC9C,QAAQ,gBAAgB,cAAc"}