@fragno-dev/db 0.2.2 → 0.4.1

package/dist/browser/hooks/hooks.d.ts

@@ -0,0 +1,146 @@
+import { DbNow } from "../query/db-now.js";
+import { FragnoId } from "../schema/create.js";
+import { RetryPolicy } from "../query/unit-of-work/retry-policy.js";
+import { ExecuteTxOptions, HandlerTxBuilder } from "../query/unit-of-work/execute-unit-of-work.js";
+import "../fragments/internal-fragment.js";
+import { DurableHooksLoggerConfig } from "./durable-hooks-logger.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 idempotency key for idempotency and database access.
+ */
+interface HookContext {
+  /**
+   * Unique idempotency key for this transaction.
+   * Use this for idempotency checks in your hook implementation.
+   */
+  idempotencyKey: string;
+  /**
+   * Hook event identifier (versioned FragnoId).
+   */
+  hookId: FragnoId;
+  /**
+   * Hook name for this event.
+   */
+  hookName: string;
+  /**
+   * Current status of the hook event.
+   */
+  status: HookStatus;
+  /**
+   * Attempt count for this hook event.
+   */
+  attempts: number;
+  /**
+   * Maximum attempts configured for this hook event.
+   */
+  maxAttempts: number;
+  /**
+   * Timestamp of the last attempt (if any).
+   */
+  lastAttemptAt: Date | null;
+  /**
+   * Next scheduled retry timestamp (if any).
+   */
+  nextRetryAt: Date | null;
+  /**
+   * When the hook event was created.
+   */
+  createdAt: Date;
+  /**
+   * Create a handler transaction builder to run atomic operations.
+   */
+  handlerTx: HookHandlerTx;
+}
+declare const hookStatusValues: readonly ["pending", "processing", "completed", "failed"];
+type HookStatus = (typeof hookStatusValues)[number];
+/**
+ * A hook function signature.
+ * Hooks receive a typed payload and access context via `this`.
+ */
+type HookFn<TPayload = unknown> = (payload: TPayload) => void | Promise<void>;
+/**
+ * Map of hook names to hook functions.
+ * Used for type-safe hook definitions and triggering.
+ */
+type HooksMap = Record<string, HookFn<any>>;
+/**
+ * Extract the payload type from a hook function.
+ */
+type HookPayload<T> = T extends HookFn<infer P> ? P : never;
+/**
+ * Options for triggering a hook.
+ */
+interface TriggerHookOptions {
+  /**
+   * Optional retry policy override for this specific hook trigger.
+   * If not provided, uses the default retry policy.
+   */
+  retryPolicy?: RetryPolicy;
+  /**
+   * Optional hook event ID. When provided, the hook insert will fail if a hook
+   * with the same ID already exists.
+   */
+  id?: string | FragnoId;
+  /**
+   * Absolute time for the first attempt. If in the future, the hook is
+   * scheduled for that time; if in the past, it runs immediately.
+   */
+  processAt?: Date | DbNow;
+}
+/**
+ * Internal representation of a triggered hook.
+ * Stored in the Unit of Work before execution.
+ */
+interface TriggeredHook {
+  namespace: string;
+  hookName: string;
+  payload: unknown;
+  options?: TriggerHookOptions;
+}
+type StuckHookProcessingTimeoutMinutes = number | false;
+type StuckHookProcessingEvent = {
+  id: FragnoId;
+  hookName: string;
+  attempts: number;
+  maxAttempts: number;
+  lastAttemptAt: Date | null;
+  nextRetryAt: Date | null;
+};
+type StuckHookProcessingInfo = {
+  namespace: string;
+  timeoutMinutes: number;
+  events: StuckHookProcessingEvent[];
+};
+type DurableHooksProcessingOptions = {
+  /**
+   * Re-queue hooks that have been in `processing` for at least this many minutes.
+   * Use `false` to disable stuck-processing recovery entirely.
+   * Values <= 0 are treated as `false`.
+   *
+   * Default: 10 minutes.
+   */
+  stuckProcessingTimeoutMinutes?: StuckHookProcessingTimeoutMinutes;
+  /**
+   * Automatically schedule hook processing after successful mutations.
+   * Defaults to true. Set false to disable auto scheduling (manual drain only).
+   */
+  autoSchedule?: boolean;
+  /**
+   * Called when stuck processing hooks are detected and re-queued.
+   * Invoked after the hooks are moved back to `pending`.
+   */
+  onStuckProcessingHooks?: (info: StuckHookProcessingInfo) => void;
+  /**
+   * Durable hooks logging controls.
+   * Defaults: enabled=true, level="warn".
+   */
+  logging?: DurableHooksLoggerConfig;
+};
+type HookHandlerTx = (execOptions?: Omit<ExecuteTxOptions, "createUnitOfWork">) => HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, HooksMap>;
+//#endregion
+export { DurableHooksProcessingOptions, HookContext, HookFn, HookHandlerTx, HookPayload, HooksMap, StuckHookProcessingEvent, StuckHookProcessingInfo, StuckHookProcessingTimeoutMinutes, TriggerHookOptions, TriggeredHook };
+//# sourceMappingURL=hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","names":[],"sources":["../../../src/hooks/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAgBA;;AAiBU,UAjBO,WAAA,CAiBP;EAYO;;;;EAYS,cAAA,EAAA,MAAA;EAGb;AAEb;AAgBA;EAOY,MAAA,EA5DF,QA4DU;EAKR;;;EAA6C,QAAA,EAAA,MAAA;EAAC;AAK1D;;EAUgB,MAAA,EAxEN,UAwEM;EAKF;;;EAOG,QAAA,EAAA,MAAa;EAyElB;AAEZ;;EAKiB,WAAA,EAAA,MAAA;EACF;;AAGf;EAMY,aAAA,EAlKK,IAkKL,GAAA,IAAA;EAQsB;;;EAeE,WAAA,EArLrB,IAqLqB,GAAA,IAAA;EAGxB;;;EAE6E,SAAA,EAtL5E,IAsL4E;EAApF;;;aAlLQ;;cAGA;KAED,UAAA,WAAqB;;;;;KAgBrB,uCAAuC,oBAAoB;;;;;KAO3D,QAAA,GAAW,eAAe;;;;KAK1B,iBAAiB,UAAU,kBAAkB;;;;UAKxC,kBAAA;;;;;gBAKD;;;;;gBAKA;;;;;cAKF,OAAO;;;;;;UAOJ,aAAA;;;;YAIL;;KAqEA,iCAAA;KAEA,wBAAA;MACN;;;;iBAIW;eACF;;KAGH,uBAAA;;;UAGF;;KAGE,6BAAA;;;;;;;;kCAQsB;;;;;;;;;;kCAUA;;;;;YAKtB;;KAGA,aAAA,kBACI,KAAK,0CAChB,oFAAoF"}

package/dist/browser/id.js

@@ -0,0 +1 @@
+import "@fragno-dev/core";

package/dist/browser/internal/adapter-registry.d.ts

@@ -0,0 +1,4 @@
+import "../sync/types.js";
+import "../fragments/internal-fragment.js";
+import "../adapters/adapters.js";
+import "./outbox-state.js";

package/dist/browser/internal/outbox-state.d.ts

@@ -0,0 +1,2 @@
+import "../outbox/outbox.js";
+import "../adapters/adapters.js";

package/dist/browser/mod.d.ts

@@ -0,0 +1,15 @@
+import { DbInterval, DbIntervalInput, DbNow, dbInterval, dbNow } from "./query/db-now.js";
+import { Cursor, CursorData, CursorResult, createCursorFromRecord, decodeCursor } from "./query/cursor.js";
+import { BuilderTransformContextWithMutate, BuilderTransformContextWithoutMutate, ExtractServiceFinalResults, ExtractServiceRetrieveResults, HandlerBuilderMutateContext, HandlerTxBuilder, ServiceBuilderMutateContext, ServiceTxBuilder, TxResult, createHandlerTxBuilder, createServiceTxBuilder } from "./query/unit-of-work/execute-unit-of-work.js";
+import { SubmitAppliedResponse, SubmitConflictReason, SubmitConflictResponse, SubmitRequest, SubmitResponse, SyncCommandDefinition, SyncCommandHandler, SyncCommandRegistry, SyncCommandTxFactory } from "./sync/types.js";
+import { IUnitOfWork, IUnitOfWorkRestricted, TypedUnitOfWork, UOWCompiler, UOWDecoder, UOWExecutor, UnitOfWork, createUnitOfWork } from "./query/unit-of-work/unit-of-work.js";
+import { withDatabase as withDatabase$1 } from "./with-database.js";
+import { defineSyncCommands } from "./sync/commands.js";
+import { migrate as migrate$1 } from "./mod2.js";
+
+//#region src/browser/mod.d.ts
+declare const withDatabase: typeof withDatabase$1;
+declare const migrate: typeof migrate$1;
+//#endregion
+export { type BuilderTransformContextWithMutate, type BuilderTransformContextWithoutMutate, Cursor, type CursorData, type CursorResult, type DbInterval, type DbIntervalInput, type DbNow, type ExtractServiceFinalResults, type ExtractServiceRetrieveResults, type HandlerBuilderMutateContext, HandlerTxBuilder, type IUnitOfWork, type IUnitOfWorkRestricted, type ServiceBuilderMutateContext, ServiceTxBuilder, type SubmitAppliedResponse, type SubmitConflictReason, type SubmitConflictResponse, type SubmitRequest, type SubmitResponse, type SyncCommandDefinition, type SyncCommandHandler, type SyncCommandRegistry, type SyncCommandTxFactory, type TxResult, TypedUnitOfWork, type UOWCompiler, type UOWDecoder, type UOWExecutor, UnitOfWork, createCursorFromRecord, createHandlerTxBuilder, createServiceTxBuilder, createUnitOfWork, dbInterval, dbNow, decodeCursor, defineSyncCommands, migrate, withDatabase };
+//# sourceMappingURL=mod.d.ts.map

package/dist/browser/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","names":[],"sources":["../../src/browser/mod.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;cA4Ca,qBAAqB;cAIrB,gBAAgB"}

package/dist/browser/mod.js

@@ -0,0 +1,17 @@
+import { HandlerTxBuilder, ServiceTxBuilder, createHandlerTxBuilder, createServiceTxBuilder } from "./query/unit-of-work/execute-unit-of-work.js";
+import { dbInterval, dbNow } from "./query/db-now.js";
+import { Cursor, createCursorFromRecord, decodeCursor } from "./query/cursor.js";
+import { TypedUnitOfWork, UnitOfWork, createUnitOfWork } from "./query/unit-of-work/unit-of-work.js";
+import { defineSyncCommands } from "./sync/commands.js";
+
+//#region src/browser/mod.ts
+const withDatabase = () => {
+	throw new Error("withDatabase is not available in browser builds.");
+};
+const migrate = async () => {
+	throw new Error("migrate is not available in browser builds.");
+};
+
+//#endregion
+export { Cursor, HandlerTxBuilder, ServiceTxBuilder, TypedUnitOfWork, UnitOfWork, createCursorFromRecord, createHandlerTxBuilder, createServiceTxBuilder, createUnitOfWork, dbInterval, dbNow, decodeCursor, defineSyncCommands, migrate, withDatabase };
+//# sourceMappingURL=mod.js.map

package/dist/browser/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["withDatabase: typeof withDatabaseType","migrate: typeof migrateType"],"sources":["../../src/browser/mod.ts"],"sourcesContent":["import type { migrate as migrateType } from \"../mod\";\nimport type { withDatabase as withDatabaseType } from \"../with-database\";\n\nexport {\n  createHandlerTxBuilder,\n  createServiceTxBuilder,\n  ServiceTxBuilder,\n  HandlerTxBuilder,\n  type TxResult,\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 {\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  Cursor,\n  decodeCursor,\n  createCursorFromRecord,\n  type CursorData,\n  type CursorResult,\n} from \"../query/cursor\";\n\nexport {\n  dbNow,\n  dbInterval,\n  type DbNow,\n  type DbInterval,\n  type DbIntervalInput,\n} from \"../query/db-now\";\n\nexport const withDatabase: typeof withDatabaseType = () => {\n  throw new Error(\"withDatabase is not available in browser builds.\");\n};\n\nexport const migrate: typeof migrateType = async () => {\n  throw new Error(\"migrate is not available in browser builds.\");\n};\n\nexport { defineSyncCommands } from \"../sync/commands\";\nexport type {\n  SubmitAppliedResponse,\n  SubmitConflictReason,\n  SubmitConflictResponse,\n  SubmitRequest,\n  SubmitResponse,\n  SyncCommandDefinition,\n  SyncCommandHandler,\n  SyncCommandRegistry,\n  SyncCommandTxFactory,\n} from \"../sync/types\";\n"],"mappings":";;;;;;;AA4CA,MAAaA,qBAA8C;AACzD,OAAM,IAAI,MAAM,mDAAmD;;AAGrE,MAAaC,UAA8B,YAAY;AACrD,OAAM,IAAI,MAAM,8CAA8C"}

package/dist/browser/mod2.d.ts

@@ -0,0 +1,48 @@
+import { DbInterval, DbIntervalInput, DbNow, dbInterval, dbNow } from "./query/db-now.js";
+import { AnySchema } from "./schema/create.js";
+import { Cursor, CursorData, CursorResult, decodeCursor } from "./query/cursor.js";
+import { RetryPolicy } from "./query/unit-of-work/retry-policy.js";
+import { BuilderTransformContextWithMutate, BuilderTransformContextWithoutMutate, ExtractServiceFinalResults, ExtractServiceRetrieveResults, HandlerBuilderMutateContext, HandlerTxBuilder, ServiceBuilderMutateContext, ServiceTxBuilder, TxResult, createHandlerTxBuilder, createServiceTxBuilder } from "./query/unit-of-work/execute-unit-of-work.js";
+import { OutboxEntry, OutboxRefMap } from "./outbox/outbox.js";
+import { SubmitAppliedResponse, SubmitConflictReason, SubmitConflictResponse, SubmitRequest, SubmitResponse, SyncCommandDefinition, SyncCommandHandler, SyncCommandRegistry, SyncCommandTxFactory } from "./sync/types.js";
+import { DatabaseFragmentDefinitionBuilder, DatabaseHandlerContext, DatabaseServiceContext, DbRoundtripGuardConfig, FragnoPublicConfigWithDatabase, ImplicitDatabaseDependencies } from "./db-fragment-definition-builder.js";
+import { InternalFragmentInstance, internalFragmentDef } from "./fragments/internal-fragment.js";
+import { DurableHooksProcessingOptions, HookContext, HookFn, HookHandlerTx, HookPayload, HooksMap, StuckHookProcessingEvent, StuckHookProcessingInfo, StuckHookProcessingTimeoutMinutes, 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 "./adapters/in-memory/index.js";
+import "./internal/adapter-registry.js";
+import { withDatabase } from "./with-database.js";
+import { defineSyncCommands } from "./sync/commands.js";
+import "./durable-hooks.js";
+import { FragnoInstantiatedFragment } from "@fragno-dev/core";
+
+//#region src/mod.d.ts
+
+type AnyFragnoInstantiatedDatabaseFragment<TSchema extends AnySchema = AnySchema> = FragnoInstantiatedFragment<any, ImplicitDatabaseDependencies<TSchema>, any, any, DatabaseHandlerContext, any, FragnoPublicConfigWithDatabase>;
+/**
+ * Helper function to run migrations for a database fragment.
+ * Extracts the database adapter, schema, and namespace from the fragment and runs migrations.
+ * This function:
+ * 1. Ensures the internal settings fragment is migrated first
+ * 2. Retrieves the current database version from the internal fragment
+ * 3. Runs migration from current version to target version
+ *
+ * @param fragment - The instantiated fragment to run migrations for
+ * @throws Error if the fragment doesn't have database support or the adapter doesn't support migrations
+ *
+ * @example
+ * ```typescript
+ * const fragment = instantiate(myFragmentDef)
+ *   .withConfig({})
+ *   .withRoutes([])
+ *   .withOptions({ databaseAdapter: myAdapter })
+ *   .build();
+ *
+ * await migrate(fragment);
+ * ```
+ */
+declare function migrate<TSchema extends AnySchema>(fragment: AnyFragnoInstantiatedDatabaseFragment<TSchema>): Promise<void>;
+//#endregion
+export { AnyFragnoInstantiatedDatabaseFragment, migrate };
+//# sourceMappingURL=mod2.d.ts.map

package/dist/browser/mod2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod2.d.ts","names":[],"sources":["../../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;KAuLY,sDAAsD,YAAY,aAC5E,gCAGE,6BAA6B,oBAK7B,6BAGA;;;;;;;;;;;;;;;;;;;;;;;iBAyBkB,wBAAwB,qBAClC,sCAAsC,WAC/C"}

package/dist/browser/naming/sql-naming.d.ts

@@ -0,0 +1,19 @@
+//#region src/naming/sql-naming.d.ts
+type NamespaceScope = "suffix" | "schema";
+interface SqlNamingStrategy {
+  namespaceScope: NamespaceScope;
+  namespaceToSchema: (namespace: string) => string;
+  tableName: (logicalTable: string, namespace: string | null) => string;
+  columnName: (logicalColumn: string, logicalTable: string) => string;
+  indexName: (logicalIndex: string, logicalTable: string, namespace: string | null) => string;
+  uniqueIndexName: (logicalIndex: string, logicalTable: string, namespace: string | null) => string;
+  foreignKeyName: (params: {
+    logicalTable: string;
+    logicalReferencedTable: string;
+    referenceName: string;
+    namespace: string | null;
+  }) => string;
+}
+//#endregion
+export { SqlNamingStrategy };
+//# sourceMappingURL=sql-naming.d.ts.map

package/dist/browser/naming/sql-naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-naming.d.ts","names":[],"sources":["../../../src/naming/sql-naming.ts"],"sourcesContent":[],"mappings":";AAIY,KAAA,cAAA,GAAc,QAAA,GAAA,QAAA;AAET,UAAA,iBAAA,CAAiB;kBAChB"}

package/dist/browser/outbox/outbox.d.ts

@@ -0,0 +1,21 @@
+import { FragnoId } from "../schema/create.js";
+import "../query/unit-of-work/unit-of-work.js";
+
+//#region src/outbox/outbox.d.ts
+
+type OutboxRefMap = Record<string, string>;
+type OutboxPayloadSerialized = {
+  json: unknown;
+  meta?: Record<string, unknown>;
+};
+type OutboxEntry = {
+  id: FragnoId;
+  versionstamp: string;
+  uowId: string;
+  payload: OutboxPayloadSerialized;
+  refMap?: OutboxRefMap;
+  createdAt: Date;
+};
+//#endregion
+export { OutboxEntry, OutboxRefMap };
+//# sourceMappingURL=outbox.d.ts.map

package/dist/browser/outbox/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","names":[],"sources":["../../../src/outbox/outbox.ts"],"sourcesContent":[],"mappings":";;;;;KAgDY,YAAA,GAAe;KAEf,uBAAA;;SAEH;;KAGG,WAAA;MACN;;;WAGK;WACA;aACE"}

package/dist/browser/query/column-defaults.js

@@ -0,0 +1 @@
+import "../id.js";

package/dist/browser/query/condition-builder.d.ts

@@ -0,0 +1,44 @@
+import { DbInterval, DbIntervalInput, DbNow } from "./db-now.js";
+import { AnyColumn, FragnoId, IdColumn } from "../schema/create.js";
+
+//#region src/query/condition-builder.d.ts
+type Condition = {
+  type: "compare";
+  a: AnyColumn;
+  operator: Operator;
+  b: AnyColumn | unknown | null;
+} | {
+  type: "or" | "and";
+  items: Condition[];
+} | {
+  type: "not";
+  item: Condition;
+};
+/**
+ * Helper type that allows FragnoId for ID columns and reference columns (bigint).
+ * Used in ConditionBuilder to accept FragnoId values in where conditions.
+ */
+type AcceptsFragnoId<T extends AnyColumn> = T extends IdColumn ? T["$in"] | FragnoId : T["$in"] extends bigint ? T["$in"] | FragnoId : T["$in"];
+type ConditionBuilder<Columns extends Record<string, AnyColumn>> = {
+  <ColName extends keyof Columns>(a: ColName, operator: (typeof valueOperators)[number] | (typeof stringOperators)[number], b: AcceptsFragnoId<Columns[ColName]> | null): Condition;
+  <ColName extends keyof Columns>(a: ColName, operator: (typeof arrayOperators)[number], b: AcceptsFragnoId<Columns[ColName]>[]): Condition;
+  /**
+   * Boolean values
+   */
+  <ColName extends keyof Columns>(a: ColName): Condition;
+  and: (...v: (Condition | boolean)[]) => Condition | boolean;
+  or: (...v: (Condition | boolean)[]) => Condition | boolean;
+  not: (v: Condition | boolean) => Condition | boolean;
+  isNull: (a: keyof Columns) => Condition;
+  isNotNull: (a: keyof Columns) => Condition;
+  now: () => DbNow;
+  interval: (input: DbIntervalInput) => DbInterval;
+};
+declare const stringOperators: readonly ["contains", "starts with", "ends with", "not contains", "not starts with", "not ends with"];
+declare const arrayOperators: readonly ["in", "not in"];
+declare const valueOperators: readonly ["=", "!=", ">", ">=", "<", "<=", "is", "is not"];
+declare const operators: readonly ["=", "!=", ">", ">=", "<", "<=", "is", "is not", "in", "not in", "contains", "starts with", "ends with", "not contains", "not starts with", "not ends with"];
+type Operator = (typeof operators)[number];
+//#endregion
+export { Condition, ConditionBuilder };
+//# sourceMappingURL=condition-builder.d.ts.map

package/dist/browser/query/condition-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition-builder.d.ts","names":[],"sources":["../../../src/query/condition-builder.ts"],"sourcesContent":[],"mappings":";;;;KAKY,SAAA;EAAA,IAAA,EAAA,SAAS;EAGZ,CAAA,EAAA,SAAA;EACO,QAAA,EAAA,QAAA;EACP,CAAA,EAAA,SAAA,GAAA,OAAA,GAAA,IAAA;CAII,GAAA;EAID,IAAA,EAAA,IAAA,GAAA,KAAA;EAAS,KAAA,EAJR,SAIQ,EAAA;AACf,CAAA,GAQD;EAA0B,IAAA,EAAA,KAAA;EAAa,IAAA,EAThC,SASgC;CAAU;;;;;KAAjD,eAGY,CAAA,UAHc,SAGd,CAAA,GAH2B,CAG3B,SAHqC,QAGrC,GAFb,CAEa,CAAA,KAAA,CAAA,GAFF,QAEE,GADb,CACa,CAAA,KAAA,CAAA,SAAA,MAAA,GAAX,CAAW,CAAA,KAAA,CAAA,GAAA,QAAA,GACX,CADW,CAAA,KAAA,CAAA;AACX,KAEM,gBAFN,CAAA,gBAEuC,MAFvC,CAAA,MAAA,EAEsD,SAFtD,CAAA,CAAA,GAAA;EAAC,CAAA,gBAAA,MAGkB,OAHlB,CAAA,CAAA,CAAA,EAIA,OAJA,EAAA,QAAA,EAAA,CAAA,OAKe,cALf,CAAA,CAAA,MAAA,CAAA,GAAA,CAAA,OAKiD,eALjD,CAAA,CAAA,MAAA,CAAA,EAAA,CAAA,EAMA,eANA,CAMgB,OANhB,CAMwB,OANxB,CAAA,CAAA,GAAA,IAAA,CAAA,EAOF,SAPE;EAEK,CAAA,gBAAA,MAOa,OAPG,CAAA,CAAA,CAAA,EAQrB,OARqB,EAAA,QAAA,EAAA,CAAA,OASN,cATM,CAAA,CAAA,MAAA,CAAA,EAAA,CAAA,EAUrB,eAVqB,CAUL,OAVK,CAUG,OAVH,CAAA,CAAA,EAAA,CAAA,EAWvB,SAXuB;EAAgC;;;EAErD,CAAA,gBAAA,MAckB,OAdlB,CAAA,CAAA,CAAA,EAc8B,OAd9B,CAAA,EAcwC,SAdxC;EACe,GAAA,EAAA,CAAA,GAAA,CAAA,EAAA,CAeP,SAfO,GAAA,OAAA,CAAA,EAAA,EAAA,GAeoB,SAfpB,GAAA,OAAA;EAAkC,EAAA,EAAA,CAAA,GAAA,CAAA,EAAA,CAgB1C,SAhB0C,GAAA,OAAA,CAAA,EAAA,EAAA,GAgBf,SAhBe,GAAA,OAAA;EACjC,GAAA,EAAA,CAAA,CAAA,EAgBZ,SAhBY,GAAA,OAAA,EAAA,GAgBY,SAhBZ,GAAA,OAAA;EAAQ,MAAA,EAAA,CAAA,CAAA,EAAA,MAkBX,OAlBW,EAAA,GAkBC,SAlBD;EAAxB,SAAA,EAAA,CAAA,CAAA,EAAA,MAmBgB,OAnBhB,EAAA,GAmB4B,SAnB5B;EACF,GAAA,EAAA,GAAA,GAmBQ,KAnBR;EAEoB,QAAA,EAAA,CAAA,KAAA,EAkBL,eAlBK,EAAA,GAkBe,UAlBf;CAClB;cAqBD,eApBgB,EAAA,SAAA,CAAA,UAAA,EAAA,aAAA,EAAA,WAAA,EAAA,cAAA,EAAA,iBAAA,EAAA,eAAA,CAAA;cA+BhB,cA9BiB,EAAA,SAAA,CAAA,IAAA,EAAA,QAAA,CAAA;cAgCjB,cAhCyB,EAAA,SAAA,CAAA,GAAA,EAAA,IAAA,EAAA,GAAA,EAAA,IAAA,EAAA,GAAA,EAAA,IAAA,EAAA,IAAA,EAAA,QAAA,CAAA;AAAxB,cAqCM,SArCN,EAAA,SAAA,CAAA,GAAA,EAAA,IAAA,EAAA,GAAA,EAAA,IAAA,EAAA,GAAA,EAAA,IAAA,EAAA,IAAA,EAAA,QAAA,EAAA,IAAA,EAAA,QAAA,EAAA,UAAA,EAAA,aAAA,EAAA,WAAA,EAAA,cAAA,EAAA,iBAAA,EAAA,eAAA,CAAA;AACF,KAsCO,QAAA,GAtCP,CAAA,OAsC0B,SAtC1B,CAAA,CAAA,MAAA,CAAA"}

package/dist/browser/query/condition-builder.js

@@ -0,0 +1,97 @@
+import { dbInterval, dbNow } from "./db-now.js";
+
+//#region src/query/condition-builder.ts
+const stringOperators = [
+	"contains",
+	"starts with",
+	"ends with",
+	"not contains",
+	"not starts with",
+	"not ends with"
+];
+const arrayOperators = ["in", "not in"];
+const valueOperators = [
+	"=",
+	"!=",
+	">",
+	">=",
+	"<",
+	"<=",
+	"is",
+	"is not"
+];
+const operators = [
+	...valueOperators,
+	...arrayOperators,
+	...stringOperators
+];
+function createBuilder(columns) {
+	function col(name) {
+		const out = columns[name];
+		if (!out) throw new Error(`Invalid column name ${String(name)}`);
+		return out;
+	}
+	const builder = (...args) => {
+		if (args.length === 3) {
+			const [a, operator, b] = args;
+			if (!operators.includes(operator)) throw new Error(`Unsupported operator: ${operator}`);
+			return {
+				type: "compare",
+				a: col(a),
+				b,
+				operator
+			};
+		}
+		return {
+			type: "compare",
+			a: col(args[0]),
+			operator: "=",
+			b: true
+		};
+	};
+	builder.isNull = (a) => builder(a, "is", null);
+	builder.isNotNull = (a) => builder(a, "is not", null);
+	builder.now = () => dbNow();
+	builder.interval = (input) => dbInterval(input);
+	builder.not = (condition) => {
+		if (typeof condition === "boolean") return !condition;
+		return {
+			type: "not",
+			item: condition
+		};
+	};
+	builder.or = (...conditions) => {
+		const out = {
+			type: "or",
+			items: []
+		};
+		for (const item of conditions) {
+			if (item === true) return true;
+			if (item === false) continue;
+			out.items.push(item);
+		}
+		if (out.items.length === 0) return false;
+		return out;
+	};
+	builder.and = (...conditions) => {
+		const out = {
+			type: "and",
+			items: []
+		};
+		for (const item of conditions) {
+			if (item === true) continue;
+			if (item === false) return false;
+			out.items.push(item);
+		}
+		if (out.items.length === 0) return true;
+		return out;
+	};
+	return builder;
+}
+function buildCondition(columns, input) {
+	return input(createBuilder(columns));
+}
+
+//#endregion
+export { buildCondition };
+//# sourceMappingURL=condition-builder.js.map

package/dist/browser/query/condition-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition-builder.js","names":["builder: ConditionBuilder<Columns>"],"sources":["../../../src/query/condition-builder.ts"],"sourcesContent":["import type { AnyColumn, FragnoId, IdColumn } from \"../schema/create\";\nimport { dbInterval, dbNow, type DbInterval, type DbIntervalInput, type DbNow } from \"./db-now\";\n\nexport type ConditionType = \"compare\" | \"and\" | \"or\" | \"not\";\n\nexport type Condition =\n  | {\n      type: \"compare\";\n      a: AnyColumn;\n      operator: Operator;\n      b: AnyColumn | unknown | null;\n    }\n  | {\n      type: \"or\" | \"and\";\n      items: Condition[];\n    }\n  | {\n      type: \"not\";\n      item: Condition;\n    };\n\n// TODO: we temporarily dropped support for comparing against another column, because Prisma ORM still have problems with it.\n\n/**\n * Helper type that allows FragnoId for ID columns and reference columns (bigint).\n * Used in ConditionBuilder to accept FragnoId values in where conditions.\n */\ntype AcceptsFragnoId<T extends AnyColumn> = T extends IdColumn\n  ? T[\"$in\"] | FragnoId\n  : T[\"$in\"] extends bigint\n    ? T[\"$in\"] | FragnoId\n    : T[\"$in\"];\n\nexport type ConditionBuilder<Columns extends Record<string, AnyColumn>> = {\n  <ColName extends keyof Columns>(\n    a: ColName,\n    operator: (typeof valueOperators)[number] | (typeof stringOperators)[number],\n    b: AcceptsFragnoId<Columns[ColName]> | null,\n  ): Condition;\n\n  <ColName extends keyof Columns>(\n    a: ColName,\n    operator: (typeof arrayOperators)[number],\n    b: AcceptsFragnoId<Columns[ColName]>[],\n  ): Condition;\n\n  /**\n   * Boolean values\n   */\n  <ColName extends keyof Columns>(a: ColName): Condition;\n\n  and: (...v: (Condition | boolean)[]) => Condition | boolean;\n  or: (...v: (Condition | boolean)[]) => Condition | boolean;\n  not: (v: Condition | boolean) => Condition | boolean;\n\n  isNull: (a: keyof Columns) => Condition;\n  isNotNull: (a: keyof Columns) => Condition;\n  now: () => DbNow;\n  interval: (input: DbIntervalInput) => DbInterval;\n};\n\n// replacement for `like` (Prisma doesn't support `like`)\nconst stringOperators = [\n  \"contains\",\n  \"starts with\",\n  \"ends with\",\n\n  \"not contains\",\n  \"not starts with\",\n  \"not ends with\",\n  // excluded `regexp` since MSSQL doesn't support it, may re-consider\n] as const;\n\nconst arrayOperators = [\"in\", \"not in\"] as const;\n\nconst valueOperators = [\"=\", \"!=\", \">\", \">=\", \"<\", \"<=\", \"is\", \"is not\"] as const;\n\n// JSON specific operators are not included, some databases don't support them\n// `match` requires additional extensions & configurations on SQLite and PostgreSQL\n// MySQL & SQLite requires workarounds to support `ilike`\nexport const operators = [...valueOperators, ...arrayOperators, ...stringOperators] as const;\n\nexport type Operator = (typeof operators)[number];\n\nexport function createBuilder<Columns extends Record<string, AnyColumn>>(\n  columns: Columns,\n): ConditionBuilder<Columns> {\n  function col(name: keyof Columns) {\n    const out = columns[name];\n    if (!out) {\n      throw new Error(`Invalid column name ${String(name)}`);\n    }\n\n    return out;\n  }\n\n  const builder: ConditionBuilder<Columns> = (...args: [string, Operator, unknown] | [string]) => {\n    if (args.length === 3) {\n      const [a, operator, b] = args;\n\n      if (!operators.includes(operator)) {\n        throw new Error(`Unsupported operator: ${operator}`);\n      }\n\n      return {\n        type: \"compare\",\n        a: col(a),\n        b,\n        operator,\n      };\n    }\n\n    return {\n      type: \"compare\",\n      a: col(args[0]),\n      operator: \"=\",\n      b: true,\n    };\n  };\n\n  builder.isNull = (a) => builder(a, \"is\", null);\n  builder.isNotNull = (a) => builder(a, \"is not\", null);\n  builder.now = () => dbNow();\n  builder.interval = (input) => dbInterval(input);\n  builder.not = (condition) => {\n    if (typeof condition === \"boolean\") {\n      return !condition;\n    }\n\n    return {\n      type: \"not\",\n      item: condition,\n    };\n  };\n\n  builder.or = (...conditions) => {\n    const out = {\n      type: \"or\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        return true;\n      }\n      if (item === false) {\n        continue;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return false;\n    }\n    return out;\n  };\n\n  builder.and = (...conditions) => {\n    const out = {\n      type: \"and\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        continue;\n      }\n      if (item === false) {\n        return false;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return true;\n    }\n    return out;\n  };\n\n  return builder;\n}\n\nexport function buildCondition<T, Columns extends Record<string, AnyColumn>>(\n  columns: Columns,\n  input: (builder: ConditionBuilder<Columns>) => T,\n): T {\n  return input(createBuilder(columns));\n}\n\n/**\n * Create a ConditionBuilder that only allows comparisons on indexed columns.\n * Used in Unit of Work to ensure queries can leverage indexes for optimal performance.\n *\n * @param columns - The full set of columns from the table\n * @param indexedColumnNames - Set of column names that are part of indexes\n * @returns A ConditionBuilder restricted to indexed columns only\n *\n * @example\n * ```ts\n * const builder = createIndexedBuilder(\n *   table.columns,\n *   new Set([\"id\", \"userId\", \"createdAt\"])\n * );\n * const condition = builder(\"userId\", \"=\", \"123\");\n * ```\n */\nexport function createIndexedBuilder<Columns extends Record<string, AnyColumn>>(\n  columns: Columns,\n  indexedColumnNames: Set<string>,\n): ConditionBuilder<Columns> {\n  function col(name: keyof Columns) {\n    const columnName = String(name);\n\n    if (!indexedColumnNames.has(columnName)) {\n      throw new Error(\n        `Column \"${columnName}\" is not indexed. Only indexed columns can be used in Unit of Work queries. ` +\n          `Available indexed columns: ${Array.from(indexedColumnNames).join(\", \")}`,\n      );\n    }\n\n    const out = columns[name];\n    if (!out) {\n      throw new Error(`Invalid column name ${columnName}`);\n    }\n\n    return out;\n  }\n\n  const builder: ConditionBuilder<Columns> = (...args: [string, Operator, unknown] | [string]) => {\n    if (args.length === 3) {\n      const [a, operator, b] = args;\n\n      if (!operators.includes(operator)) {\n        throw new Error(`Unsupported operator: ${operator}`);\n      }\n\n      return {\n        type: \"compare\",\n        a: col(a),\n        b,\n        operator,\n      };\n    }\n\n    return {\n      type: \"compare\",\n      a: col(args[0]),\n      operator: \"=\",\n      b: true,\n    };\n  };\n\n  builder.isNull = (a) => builder(a, \"is\", null);\n  builder.isNotNull = (a) => builder(a, \"is not\", null);\n  builder.now = () => dbNow();\n  builder.interval = (input) => dbInterval(input);\n  builder.not = (condition) => {\n    if (typeof condition === \"boolean\") {\n      return !condition;\n    }\n\n    return {\n      type: \"not\",\n      item: condition,\n    };\n  };\n\n  builder.or = (...conditions) => {\n    const out = {\n      type: \"or\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        return true;\n      }\n      if (item === false) {\n        continue;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return false;\n    }\n    return out;\n  };\n\n  builder.and = (...conditions) => {\n    const out = {\n      type: \"and\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        continue;\n      }\n      if (item === false) {\n        return false;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return true;\n    }\n    return out;\n  };\n\n  return builder;\n}\n"],"mappings":";;;AA8DA,MAAM,kBAAkB;CACtB;CACA;CACA;CAEA;CACA;CACA;CAED;AAED,MAAM,iBAAiB,CAAC,MAAM,SAAS;AAEvC,MAAM,iBAAiB;CAAC;CAAK;CAAM;CAAK;CAAM;CAAK;CAAM;CAAM;CAAS;AAKxE,MAAa,YAAY;CAAC,GAAG;CAAgB,GAAG;CAAgB,GAAG;CAAgB;AAInF,SAAgB,cACd,SAC2B;CAC3B,SAAS,IAAI,MAAqB;EAChC,MAAM,MAAM,QAAQ;AACpB,MAAI,CAAC,IACH,OAAM,IAAI,MAAM,uBAAuB,OAAO,KAAK,GAAG;AAGxD,SAAO;;CAGT,MAAMA,WAAsC,GAAG,SAAiD;AAC9F,MAAI,KAAK,WAAW,GAAG;GACrB,MAAM,CAAC,GAAG,UAAU,KAAK;AAEzB,OAAI,CAAC,UAAU,SAAS,SAAS,CAC/B,OAAM,IAAI,MAAM,yBAAyB,WAAW;AAGtD,UAAO;IACL,MAAM;IACN,GAAG,IAAI,EAAE;IACT;IACA;IACD;;AAGH,SAAO;GACL,MAAM;GACN,GAAG,IAAI,KAAK,GAAG;GACf,UAAU;GACV,GAAG;GACJ;;AAGH,SAAQ,UAAU,MAAM,QAAQ,GAAG,MAAM,KAAK;AAC9C,SAAQ,aAAa,MAAM,QAAQ,GAAG,UAAU,KAAK;AACrD,SAAQ,YAAY,OAAO;AAC3B,SAAQ,YAAY,UAAU,WAAW,MAAM;AAC/C,SAAQ,OAAO,cAAc;AAC3B,MAAI,OAAO,cAAc,UACvB,QAAO,CAAC;AAGV,SAAO;GACL,MAAM;GACN,MAAM;GACP;;AAGH,SAAQ,MAAM,GAAG,eAAe;EAC9B,MAAM,MAAM;GACV,MAAM;GACN,OAAO,EAAE;GACV;AAED,OAAK,MAAM,QAAQ,YAAY;AAC7B,OAAI,SAAS,KACX,QAAO;AAET,OAAI,SAAS,MACX;AAGF,OAAI,MAAM,KAAK,KAAK;;AAGtB,MAAI,IAAI,MAAM,WAAW,EACvB,QAAO;AAET,SAAO;;AAGT,SAAQ,OAAO,GAAG,eAAe;EAC/B,MAAM,MAAM;GACV,MAAM;GACN,OAAO,EAAE;GACV;AAED,OAAK,MAAM,QAAQ,YAAY;AAC7B,OAAI,SAAS,KACX;AAEF,OAAI,SAAS,MACX,QAAO;AAGT,OAAI,MAAM,KAAK,KAAK;;AAGtB,MAAI,IAAI,MAAM,WAAW,EACvB,QAAO;AAET,SAAO;;AAGT,QAAO;;AAGT,SAAgB,eACd,SACA,OACG;AACH,QAAO,MAAM,cAAc,QAAQ,CAAC"}

package/dist/browser/query/cursor.d.ts

@@ -0,0 +1,105 @@
+import { AnyColumn } from "../schema/create.js";
+
+//#region src/query/cursor.d.ts
+
+/**
+ * Cursor object containing all information needed for pagination
+ */
+declare class Cursor {
+  #private;
+  constructor(data: {
+    indexName: string;
+    orderDirection: "asc" | "desc";
+    pageSize: number;
+    indexValues: Record<string, unknown>;
+  });
+  /**
+   * Get the index name being used for pagination
+   */
+  get indexName(): string;
+  /**
+   * Get the ordering direction
+   */
+  get orderDirection(): "asc" | "desc";
+  /**
+   * Get the page size
+   */
+  get pageSize(): number;
+  /**
+   * Get the cursor position values
+   */
+  get indexValues(): Record<string, unknown>;
+  /**
+   * Encode cursor to an opaque base64 string (safe to send to client)
+   */
+  encode(): string;
+}
+/**
+ * Result of a cursor-based query containing items and pagination cursor
+ */
+interface CursorResult<T> {
+  /**
+   * The query results
+   */
+  items: T[];
+  /**
+   * Cursor to fetch the next page (undefined if no more results)
+   */
+  cursor?: Cursor;
+  /**
+   * Whether there are more results available after this page
+   */
+  hasNextPage: boolean;
+}
+/**
+ * Cursor data structure for serialization
+ */
+interface CursorData {
+  v: number;
+  indexName: string;
+  orderDirection: "asc" | "desc";
+  pageSize: number;
+  indexValues: Record<string, unknown>;
+}
+/**
+ * Decode a base64 cursor string back to a Cursor object
+ *
+ * @param cursor - The base64-encoded cursor string
+ * @returns Decoded Cursor object
+ * @throws Error if cursor is invalid or malformed
+ *
+ * @example
+ * ```ts
+ * const cursor = decodeCursor("eyJpbmRleFZhbHVlcyI6e30sImRpcmVjdGlvbiI6ImZvcndhcmQifQ==");
+ * ```
+ */
+declare function decodeCursor(cursor: string): Cursor;
+/**
+ * Create a cursor from a record and pagination metadata
+ *
+ * @param record - The database record
+ * @param indexColumns - The columns that make up the index
+ * @param metadata - Pagination metadata (index name, order direction, page size)
+ * @returns Cursor object
+ *
+ * @example
+ * ```ts
+ * const cursor = createCursorFromRecord(
+ *   { id: "abc", name: "Alice", createdAt: 123 },
+ *   [table.columns.createdAt, table.columns.id],
+ *   {
+ *     indexName: "idx_created",
+ *     orderDirection: "asc",
+ *     pageSize: 10
+ *   }
+ * );
+ * ```
+ */
+declare function createCursorFromRecord(record: Record<string, unknown>, indexColumns: AnyColumn[], metadata: {
+  indexName: string;
+  orderDirection: "asc" | "desc";
+  pageSize: number;
+}): Cursor;
+//#endregion
+export { Cursor, CursorData, CursorResult, createCursorFromRecord, decodeCursor };
+//# sourceMappingURL=cursor.d.ts.map

package/dist/browser/query/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","names":[],"sources":["../../../src/query/cursor.ts"],"sourcesContent":[],"mappings":";;;;AASA;AAiEA;AAkBA;AAqCgB,cAxHH,MAAA,CAwHe;EAoEZ,CAAA,OAAA;EACN,WAAA,CAAA,IAAA,EAAA;IACM,SAAA,EAAA,MAAA;IAMb,cAAA,EAAA,KAAA,GAAA,MAAA;IAAM,QAAA,EAAA,MAAA;iBA1LQ;;;;;;;;;;;;;;;;;qBAgCI;;;;;;;;;UAuBJ;;;;SAIR;;;;WAIE;;;;;;;;;UAUM,UAAA;;;;;eAKF;;;;;;;;;;;;;;iBAgCC,YAAA,kBAA8B;;;;;;;;;;;;;;;;;;;;;;iBAoE9B,sBAAA,SACN,uCACM;;;;IAMb"}