better-call 0.0.0-experimental.01ff4b77

package/dist/storage.d.cts

@@ -0,0 +1,220 @@
+import { OnEntry } from "./module.cjs";
+import { NameOfVar, ValueOfVar, VarDefination } from "./var.cjs";
+//#region src/storage.d.ts
+/** Per-field operators, for everything equality can't say: expiry sweeps
+ * (`lt`), revocation lists (`in`), guarded counters (`lt` as the guard).
+ * A bare value stays plain equality - the common case reads like data. */
+type WhereOps<V> = {
+  eq?: V;
+  ne?: V;
+  lt?: V;
+  lte?: V;
+  gt?: V;
+  gte?: V;
+  in?: readonly V[];
+  notIn?: readonly V[];
+  contains?: string;
+  startsWith?: string;
+  endsWith?: string;
+};
+type WhereOp = keyof WhereOps<unknown>;
+/** AND across fields; each field a bare value (equality) or operators. */
+type Where<R> = { [K in keyof R]?: R[K] | WhereOps<R[K]>; };
+/** One normalized clause: `{ tag: "a" }` -> `{ field: "tag", op: "eq" }`. */
+type Condition = {
+  field: string;
+  op: WhereOp;
+  value: unknown;
+};
+/** Flatten a where to normalized conditions - the adapter author's
+ * translation seam: map each condition onto your query language, AND them. */
+declare const conditionsOf: (where?: Record<string, unknown>) => Condition[];
+/** Does a row satisfy a where? The in-memory evaluator - the dummy adapter
+ * runs on it, and any adapter over an unqueryable backend can too. */
+declare const matchesWhere: (row: Record<string, unknown>, where?: Record<string, unknown>) => boolean;
+/** Shaping for `findMany`: sort, then window. */
+type FindManyOptions<R> = {
+  limit?: number;
+  offset?: number;
+  sortBy?: {
+    field: keyof R & string;
+    direction?: "asc" | "desc";
+  };
+};
+/** One model's CRUD surface. `create` is generic so a row EXTENDED by a
+ * mounted module (an account with a password field) keeps its extra
+ * fields through the round-trip outside a widened scope. Inside a scope
+ * that mounts `v.extend` / same-name customize on the model var, {@link
+ * WidenSchemaFns} rewrites `R` (see `$modelVar`) the same way it widens
+ * `v.fn.type({ input: user })`. */
+type Collection<R, N extends string = string> = {
+  create: <T extends R>(data: T) => Promise<T>;
+  findOne: (where: Where<R>) => Promise<R | null>;
+  findMany: (where?: Where<R>, options?: FindManyOptions<R>) => Promise<R[]>;
+  /** Merge `patch` into the FIRST match - null when nothing matched. */
+  update: (where: Where<R>, patch: Partial<R>) => Promise<R | null>;
+  /** Remove every match; how many is the answer. */
+  delete: (where: Where<R>) => Promise<number>;
+  count: (where?: Where<R>) => Promise<number>;
+  /** Claim the FIRST match: the row comes back and is GONE, atomically -
+   * two racing consumers never both get it. Single-use credentials
+   * (verification tokens, one-time codes) hang off this. */
+  consumeOne: (where: Where<R>) => Promise<R | null>;
+  /** Add to numeric fields of the FIRST match, atomically; the where is
+   * also the GUARD (`count: { lt: max }`), so check-and-bump is one op -
+   * null means no row passed it. Rate limiting hangs off this. */
+  incrementOne: (where: Where<R>, increments: Partial<Record<keyof R & string, number>>) => Promise<R | null>;
+  /**
+   * Phantom: the model var's name. Scope resolution reads it to WIDEN
+   * `R` with everything the scope mounts on that var - same role as
+   * `$fnVar` on fn schemas. Optional, so plain collection objects still
+   * satisfy the type.
+   */
+  readonly $modelVar?: [N];
+};
+/**
+ * What a real database implements: six required verbs, models addressed by
+ * NAME, `where` as bare-equality fields and/or operator objects
+ * (`conditionsOf` normalizes either form). The storage API above never
+ * changes - adapters translate it, sync or async.
+ *
+ * The optional verbs are ATOMICITY upgrades: without `consumeOne` /
+ * `incrementOne` the storage falls back to find-then-write - correct alone,
+ * racy under contention - and without `transaction` a `$transaction` block
+ * runs plainly. Implement them where the backend has the primitive.
+ */
+type StorageAdapter = {
+  create: (model: string, data: Record<string, unknown>) => unknown;
+  findOne: (model: string, where: Record<string, unknown>) => unknown;
+  findMany: (model: string, where?: Record<string, unknown>, options?: FindManyOptions<Record<string, unknown>>) => unknown;
+  update: (model: string, where: Record<string, unknown>, patch: Record<string, unknown>) => unknown;
+  delete: (model: string, where: Record<string, unknown>) => unknown;
+  count: (model: string, where?: Record<string, unknown>) => unknown;
+  /** Atomic find-and-delete of the first match. */
+  consumeOne?: (model: string, where: Record<string, unknown>) => unknown;
+  /** Atomic guarded add to numeric fields of the first match. */
+  incrementOne?: (model: string, where: Record<string, unknown>, increments: Record<string, number>) => unknown;
+  /** Run `run` against a transaction-bound view of this adapter:
+   * committed when it resolves, rolled back when it throws. */
+  transaction?: <T>(run: (tx: StorageAdapter) => Promise<T>) => Promise<T>;
+};
+/** The DUMMY adapter: rows in arrays, one per model. Implements the whole
+ * surface - the optional verbs by mutation (single-threaded, so "atomic"),
+ * transactions by snapshot-and-restore. */
+declare const memoryAdapter: () => StorageAdapter;
+type AnyVar = VarDefination<any, any, any, any>;
+/** Persistence facts about one field the ROW SHAPE can't say - consumed by
+ * schema generators and adapters, never acted on by the runtime. (Read
+ * shaping like redaction is a `$on` hook, not metadata.) Prefer declaring
+ * these via `db.unique` / `db.indexed` / `db.references` / `db.id` on the
+ * field schema; `ModelConfig.fields` remains an override. */
+type FieldMeta = {
+  /** Primary key for this model. */
+  id?: boolean;
+  /** No two rows share a value. */
+  unique?: boolean;
+  /** Worth an index. */
+  index?: boolean;
+  /** Foreign key: this field holds `model.field` values. */
+  references?: {
+    model: string;
+    field: string;
+    onDelete?: "cascade" | "set null" | "restrict";
+  };
+};
+/** Read `$attrs.db` off each field of a var's object schema. */
+declare const fieldsFromSchema: (sv: AnyVar) => Record<string, FieldMeta>;
+/**
+ * Schema attrs first; `ModelConfig.fields[k]` replaces that key entirely
+ * when present (compat override).
+ */
+declare const resolveModelFields: (input: ModelInput) => Record<string, FieldMeta> | undefined;
+/** What an op subscription hands back: `v.on` entries to mount. */
+type SubscriptionEntries = OnEntry<string> | readonly OnEntry<string>[];
+/**
+ * A model declared WITH its persistence: `schema` is the var (the shape),
+ * `fields` carries per-field storage metadata, and each op key SUBSCRIBES
+ * that op to app events - handed the bound collection op, it returns `v.on`
+ * entries that mount wherever the storage does (`use: [db]`). An
+ * already-built entry works in place of the fn.
+ */
+type ModelConfig<SV extends AnyVar = AnyVar> = {
+  schema: SV;
+  fields?: { [F in keyof NonNullable<ValueOfVar<SV>>]?: FieldMeta; };
+} & { [Op in StorageOp]?: ((action: Collection<NonNullable<ValueOfVar<SV>>>[Op]) => SubscriptionEntries) | SubscriptionEntries; };
+/** A model is a bare var, or a config carrying the var as `schema`. */
+type ModelInput = AnyVar | ModelConfig;
+/** The var behind a model input. Checked through `$var`, never `schema` -
+ * a bare var also HAS a `schema` property (its type shape). */
+type SchemaOf<T> = T extends {
+  $var: true;
+} ? T : T extends {
+  schema: infer SV;
+} ? SV : never;
+type RowOf<T> = NonNullable<ValueOfVar<SchemaOf<T>>>;
+/** Declared name of the var behind a model input - brands the collection. */
+type ModelVarName<T> = NameOfVar<SchemaOf<T>> & string;
+type StorageModels = Record<string, ModelInput>;
+type StorageOp = "create" | "findOne" | "findMany" | "update" | "delete" | "count" | "consumeOne" | "incrementOne";
+/** What a storage hook sees: which model and op, with the op's arguments
+ * positionally (`create` -> [data], `update` -> [where, patch], `findMany`
+ * -> [where, options], `incrementOne` -> [where, increments], ...). */
+type StorageHookContext = {
+  /** The model KEY being addressed (the storage's property name). */
+  model: string;
+  op: StorageOp;
+  args: readonly unknown[];
+};
+/** `next()` runs the op (hooks below it included) and resolves its result;
+ * the hook's own return value IS the op's result - wrap, veto, transform. */
+type StorageHook = (c: StorageHookContext, next: () => Promise<unknown>) => unknown;
+/** Every target a storage hook can name - a flat union, so editors offer
+ * the whole surface: exact ("user.create"), per-model ("user.*"), per-op
+ * ("*.create"), everything ("*"). */
+type StorageTarget<M> = "*" | `${keyof M & string}.${StorageOp | "*"}` | `*.${StorageOp}`;
+type Storage<M extends StorageModels> = { [K in keyof M]: Collection<RowOf<M[K]>, ModelVarName<M[K]>>; } & StorageApi<M>;
+/** Duck-type a storage instance - `$models` plus the `$adapter` method. */
+declare const isStorage: (value: unknown) => value is Storage<StorageModels>;
+/** The customization surface, `$`-prefixed so model keys never collide. */
+type StorageApi<M extends StorageModels> = {
+  /** Swap the backend IN PLACE: every view of this storage - and every
+   * module that captured it - starts hitting the new adapter. */
+  $adapter: (adapter: StorageAdapter) => Storage<M>;
+  /** Intercept ops: hooks stack in mount order and apply to every view
+   * sharing this storage's state. */
+  $on: (target: StorageTarget<M>, hook: StorageHook) => Storage<M>;
+  /** A view WITHOUT these models - same adapter, same hooks. */
+  $omit: <K extends keyof M & string>(...keys: K[]) => Storage<Omit<M, K>>;
+  /** A view of ONLY these models - same adapter, same hooks. */
+  $pick: <K extends keyof M & string>(...keys: K[]) => Storage<Pick<M, K>>;
+  /** A view with MORE models - same adapter, same hooks. */
+  $extend: <M2 extends StorageModels>(models: M2) => Storage<M & M2>;
+  /** Run `fn` against a view whose ops share ONE adapter transaction -
+   * committed when it resolves, rolled back when it throws. Same models,
+   * same hooks (they run inside). An adapter without `transaction` runs
+   * `fn` plainly - no atomicity, same answer. */
+  $transaction: <T>(fn: (tx: Storage<M>) => Promise<T> | T) => Promise<T>;
+  /** The model definitions this view exposes. */
+  $models: M;
+};
+/**
+ * MANY instances of a var: each model is a collection of rows shaped like
+ * the var's VALUE, addressed by the var's NAME - the var stays what it
+ * always was (the scope's one current instance), the storage holds every
+ * other one, and the query API is how rows move between the two.
+ *
+ * The returned storage is CUSTOMIZABLE through its `$` surface: `$adapter`
+ * swaps the backend in place, `$on` mounts hooks around ops,
+ * `$omit`/`$pick`/`$extend` derive model views over the same state, and
+ * `$transaction` scopes ops to one adapter transaction.
+ *
+ * A model can also DECLARE its persistence: pass `{ schema, create: ... }`
+ * instead of the bare var, and the op subscriptions ride on the storage as
+ * mountable `v.on` entries - `use: [db]` wires them into the app. The same
+ * config carries `fields` metadata (unique, index, references) for schema
+ * generators to consume.
+ */
+declare const makeStorage: <const M extends StorageModels>(adapter: StorageAdapter, models: M) => Storage<M>;
+//#endregion
+export { Collection, Condition, FieldMeta, FindManyOptions, ModelConfig, Storage, StorageAdapter, StorageApi, StorageHook, StorageHookContext, StorageModels, StorageOp, StorageTarget, Where, WhereOp, WhereOps, conditionsOf, fieldsFromSchema, isStorage, makeStorage, matchesWhere, memoryAdapter, resolveModelFields };
+//# sourceMappingURL=storage.d.cts.map

package/dist/storage.d.mts

@@ -0,0 +1,220 @@
+import { OnEntry } from "./module.mjs";
+import { NameOfVar, ValueOfVar, VarDefination } from "./var.mjs";
+//#region src/storage.d.ts
+/** Per-field operators, for everything equality can't say: expiry sweeps
+ * (`lt`), revocation lists (`in`), guarded counters (`lt` as the guard).
+ * A bare value stays plain equality - the common case reads like data. */
+type WhereOps<V> = {
+  eq?: V;
+  ne?: V;
+  lt?: V;
+  lte?: V;
+  gt?: V;
+  gte?: V;
+  in?: readonly V[];
+  notIn?: readonly V[];
+  contains?: string;
+  startsWith?: string;
+  endsWith?: string;
+};
+type WhereOp = keyof WhereOps<unknown>;
+/** AND across fields; each field a bare value (equality) or operators. */
+type Where<R> = { [K in keyof R]?: R[K] | WhereOps<R[K]>; };
+/** One normalized clause: `{ tag: "a" }` -> `{ field: "tag", op: "eq" }`. */
+type Condition = {
+  field: string;
+  op: WhereOp;
+  value: unknown;
+};
+/** Flatten a where to normalized conditions - the adapter author's
+ * translation seam: map each condition onto your query language, AND them. */
+declare const conditionsOf: (where?: Record<string, unknown>) => Condition[];
+/** Does a row satisfy a where? The in-memory evaluator - the dummy adapter
+ * runs on it, and any adapter over an unqueryable backend can too. */
+declare const matchesWhere: (row: Record<string, unknown>, where?: Record<string, unknown>) => boolean;
+/** Shaping for `findMany`: sort, then window. */
+type FindManyOptions<R> = {
+  limit?: number;
+  offset?: number;
+  sortBy?: {
+    field: keyof R & string;
+    direction?: "asc" | "desc";
+  };
+};
+/** One model's CRUD surface. `create` is generic so a row EXTENDED by a
+ * mounted module (an account with a password field) keeps its extra
+ * fields through the round-trip outside a widened scope. Inside a scope
+ * that mounts `v.extend` / same-name customize on the model var, {@link
+ * WidenSchemaFns} rewrites `R` (see `$modelVar`) the same way it widens
+ * `v.fn.type({ input: user })`. */
+type Collection<R, N extends string = string> = {
+  create: <T extends R>(data: T) => Promise<T>;
+  findOne: (where: Where<R>) => Promise<R | null>;
+  findMany: (where?: Where<R>, options?: FindManyOptions<R>) => Promise<R[]>;
+  /** Merge `patch` into the FIRST match - null when nothing matched. */
+  update: (where: Where<R>, patch: Partial<R>) => Promise<R | null>;
+  /** Remove every match; how many is the answer. */
+  delete: (where: Where<R>) => Promise<number>;
+  count: (where?: Where<R>) => Promise<number>;
+  /** Claim the FIRST match: the row comes back and is GONE, atomically -
+   * two racing consumers never both get it. Single-use credentials
+   * (verification tokens, one-time codes) hang off this. */
+  consumeOne: (where: Where<R>) => Promise<R | null>;
+  /** Add to numeric fields of the FIRST match, atomically; the where is
+   * also the GUARD (`count: { lt: max }`), so check-and-bump is one op -
+   * null means no row passed it. Rate limiting hangs off this. */
+  incrementOne: (where: Where<R>, increments: Partial<Record<keyof R & string, number>>) => Promise<R | null>;
+  /**
+   * Phantom: the model var's name. Scope resolution reads it to WIDEN
+   * `R` with everything the scope mounts on that var - same role as
+   * `$fnVar` on fn schemas. Optional, so plain collection objects still
+   * satisfy the type.
+   */
+  readonly $modelVar?: [N];
+};
+/**
+ * What a real database implements: six required verbs, models addressed by
+ * NAME, `where` as bare-equality fields and/or operator objects
+ * (`conditionsOf` normalizes either form). The storage API above never
+ * changes - adapters translate it, sync or async.
+ *
+ * The optional verbs are ATOMICITY upgrades: without `consumeOne` /
+ * `incrementOne` the storage falls back to find-then-write - correct alone,
+ * racy under contention - and without `transaction` a `$transaction` block
+ * runs plainly. Implement them where the backend has the primitive.
+ */
+type StorageAdapter = {
+  create: (model: string, data: Record<string, unknown>) => unknown;
+  findOne: (model: string, where: Record<string, unknown>) => unknown;
+  findMany: (model: string, where?: Record<string, unknown>, options?: FindManyOptions<Record<string, unknown>>) => unknown;
+  update: (model: string, where: Record<string, unknown>, patch: Record<string, unknown>) => unknown;
+  delete: (model: string, where: Record<string, unknown>) => unknown;
+  count: (model: string, where?: Record<string, unknown>) => unknown;
+  /** Atomic find-and-delete of the first match. */
+  consumeOne?: (model: string, where: Record<string, unknown>) => unknown;
+  /** Atomic guarded add to numeric fields of the first match. */
+  incrementOne?: (model: string, where: Record<string, unknown>, increments: Record<string, number>) => unknown;
+  /** Run `run` against a transaction-bound view of this adapter:
+   * committed when it resolves, rolled back when it throws. */
+  transaction?: <T>(run: (tx: StorageAdapter) => Promise<T>) => Promise<T>;
+};
+/** The DUMMY adapter: rows in arrays, one per model. Implements the whole
+ * surface - the optional verbs by mutation (single-threaded, so "atomic"),
+ * transactions by snapshot-and-restore. */
+declare const memoryAdapter: () => StorageAdapter;
+type AnyVar = VarDefination<any, any, any, any>;
+/** Persistence facts about one field the ROW SHAPE can't say - consumed by
+ * schema generators and adapters, never acted on by the runtime. (Read
+ * shaping like redaction is a `$on` hook, not metadata.) Prefer declaring
+ * these via `db.unique` / `db.indexed` / `db.references` / `db.id` on the
+ * field schema; `ModelConfig.fields` remains an override. */
+type FieldMeta = {
+  /** Primary key for this model. */
+  id?: boolean;
+  /** No two rows share a value. */
+  unique?: boolean;
+  /** Worth an index. */
+  index?: boolean;
+  /** Foreign key: this field holds `model.field` values. */
+  references?: {
+    model: string;
+    field: string;
+    onDelete?: "cascade" | "set null" | "restrict";
+  };
+};
+/** Read `$attrs.db` off each field of a var's object schema. */
+declare const fieldsFromSchema: (sv: AnyVar) => Record<string, FieldMeta>;
+/**
+ * Schema attrs first; `ModelConfig.fields[k]` replaces that key entirely
+ * when present (compat override).
+ */
+declare const resolveModelFields: (input: ModelInput) => Record<string, FieldMeta> | undefined;
+/** What an op subscription hands back: `v.on` entries to mount. */
+type SubscriptionEntries = OnEntry<string> | readonly OnEntry<string>[];
+/**
+ * A model declared WITH its persistence: `schema` is the var (the shape),
+ * `fields` carries per-field storage metadata, and each op key SUBSCRIBES
+ * that op to app events - handed the bound collection op, it returns `v.on`
+ * entries that mount wherever the storage does (`use: [db]`). An
+ * already-built entry works in place of the fn.
+ */
+type ModelConfig<SV extends AnyVar = AnyVar> = {
+  schema: SV;
+  fields?: { [F in keyof NonNullable<ValueOfVar<SV>>]?: FieldMeta; };
+} & { [Op in StorageOp]?: ((action: Collection<NonNullable<ValueOfVar<SV>>>[Op]) => SubscriptionEntries) | SubscriptionEntries; };
+/** A model is a bare var, or a config carrying the var as `schema`. */
+type ModelInput = AnyVar | ModelConfig;
+/** The var behind a model input. Checked through `$var`, never `schema` -
+ * a bare var also HAS a `schema` property (its type shape). */
+type SchemaOf<T> = T extends {
+  $var: true;
+} ? T : T extends {
+  schema: infer SV;
+} ? SV : never;
+type RowOf<T> = NonNullable<ValueOfVar<SchemaOf<T>>>;
+/** Declared name of the var behind a model input - brands the collection. */
+type ModelVarName<T> = NameOfVar<SchemaOf<T>> & string;
+type StorageModels = Record<string, ModelInput>;
+type StorageOp = "create" | "findOne" | "findMany" | "update" | "delete" | "count" | "consumeOne" | "incrementOne";
+/** What a storage hook sees: which model and op, with the op's arguments
+ * positionally (`create` -> [data], `update` -> [where, patch], `findMany`
+ * -> [where, options], `incrementOne` -> [where, increments], ...). */
+type StorageHookContext = {
+  /** The model KEY being addressed (the storage's property name). */
+  model: string;
+  op: StorageOp;
+  args: readonly unknown[];
+};
+/** `next()` runs the op (hooks below it included) and resolves its result;
+ * the hook's own return value IS the op's result - wrap, veto, transform. */
+type StorageHook = (c: StorageHookContext, next: () => Promise<unknown>) => unknown;
+/** Every target a storage hook can name - a flat union, so editors offer
+ * the whole surface: exact ("user.create"), per-model ("user.*"), per-op
+ * ("*.create"), everything ("*"). */
+type StorageTarget<M> = "*" | `${keyof M & string}.${StorageOp | "*"}` | `*.${StorageOp}`;
+type Storage<M extends StorageModels> = { [K in keyof M]: Collection<RowOf<M[K]>, ModelVarName<M[K]>>; } & StorageApi<M>;
+/** Duck-type a storage instance - `$models` plus the `$adapter` method. */
+declare const isStorage: (value: unknown) => value is Storage<StorageModels>;
+/** The customization surface, `$`-prefixed so model keys never collide. */
+type StorageApi<M extends StorageModels> = {
+  /** Swap the backend IN PLACE: every view of this storage - and every
+   * module that captured it - starts hitting the new adapter. */
+  $adapter: (adapter: StorageAdapter) => Storage<M>;
+  /** Intercept ops: hooks stack in mount order and apply to every view
+   * sharing this storage's state. */
+  $on: (target: StorageTarget<M>, hook: StorageHook) => Storage<M>;
+  /** A view WITHOUT these models - same adapter, same hooks. */
+  $omit: <K extends keyof M & string>(...keys: K[]) => Storage<Omit<M, K>>;
+  /** A view of ONLY these models - same adapter, same hooks. */
+  $pick: <K extends keyof M & string>(...keys: K[]) => Storage<Pick<M, K>>;
+  /** A view with MORE models - same adapter, same hooks. */
+  $extend: <M2 extends StorageModels>(models: M2) => Storage<M & M2>;
+  /** Run `fn` against a view whose ops share ONE adapter transaction -
+   * committed when it resolves, rolled back when it throws. Same models,
+   * same hooks (they run inside). An adapter without `transaction` runs
+   * `fn` plainly - no atomicity, same answer. */
+  $transaction: <T>(fn: (tx: Storage<M>) => Promise<T> | T) => Promise<T>;
+  /** The model definitions this view exposes. */
+  $models: M;
+};
+/**
+ * MANY instances of a var: each model is a collection of rows shaped like
+ * the var's VALUE, addressed by the var's NAME - the var stays what it
+ * always was (the scope's one current instance), the storage holds every
+ * other one, and the query API is how rows move between the two.
+ *
+ * The returned storage is CUSTOMIZABLE through its `$` surface: `$adapter`
+ * swaps the backend in place, `$on` mounts hooks around ops,
+ * `$omit`/`$pick`/`$extend` derive model views over the same state, and
+ * `$transaction` scopes ops to one adapter transaction.
+ *
+ * A model can also DECLARE its persistence: pass `{ schema, create: ... }`
+ * instead of the bare var, and the op subscriptions ride on the storage as
+ * mountable `v.on` entries - `use: [db]` wires them into the app. The same
+ * config carries `fields` metadata (unique, index, references) for schema
+ * generators to consume.
+ */
+declare const makeStorage: <const M extends StorageModels>(adapter: StorageAdapter, models: M) => Storage<M>;
+//#endregion
+export { Collection, Condition, FieldMeta, FindManyOptions, ModelConfig, Storage, StorageAdapter, StorageApi, StorageHook, StorageHookContext, StorageModels, StorageOp, StorageTarget, Where, WhereOp, WhereOps, conditionsOf, fieldsFromSchema, isStorage, makeStorage, matchesWhere, memoryAdapter, resolveModelFields };
+//# sourceMappingURL=storage.d.mts.map