better-call 0.0.0-experimental.06264e12

package/dist/schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.mjs","names":[],"sources":["../src/schema.ts"],"sourcesContent":["import { type Issue, ValidationError } from \"./error\";\nimport type { LiteralString, Prettify } from \"./types\";\n\nexport type Rules = {\n\t/** Strings: length. Numbers: value. */\n\tmin?: number;\n\t/** Strings: length. Numbers: value. */\n\tmax?: number;\n\t/** Strings only: exact length. */\n\tlength?: number;\n\tregex?: RegExp;\n\temail?: boolean;\n\turl?: boolean;\n\tstartsWith?: string;\n\tendsWith?: string;\n\t/** Numbers only. */\n\tint?: boolean;\n\t/** Allowed values. */\n\tenum?: readonly unknown[];\n\t/** Escape hatch - return true, or a message to fail with. */\n\tcheck?: (value: any) => boolean | string;\n};\n\nexport interface TypeDefination<T, O, D = never> extends Rules {\n\tname: LiteralString;\n\ttype?: T;\n\toutput?: O;\n\tshape?: unknown;\n\t/** `function` types only: the declared input of the expected fn -\n\t * plain closures get it validated at their door on every call. */\n\tfnInput?: unknown;\n\t/** Used when the incoming value is `undefined`. */\n\tdefault?: D;\n\t/** When true, `undefined` passes straight through unvalidated. */\n\toptional?: boolean;\n\ttransform?: (value: any) => O;\n}\n\nexport type TypeOptions<T, O> = {\n\ttransform?: (value: T) => O;\n};\n\ntype WithDefault<D> = { default?: D };\n\ntype WithOptional<Opt> = { optional?: Opt };\n\n/**\n * `optional` widens the output; `default` keeps it narrow because a value\n * is always produced. Declaring both means optional to send, never absent.\n */\ntype OutOf<O, D, Opt> = [Opt] extends [true]\n\t? [D] extends [never]\n\t\t? O | undefined\n\t\t: O\n\t: O;\n\n/** Either marker makes the key omittable in `InferArgs`. */\ntype DefOf<D, Opt> = [Opt] extends [true]\n\t? [D] extends [never]\n\t\t? undefined\n\t\t: D\n\t: D;\n\ntype StringOptions<E extends string, O> = TypeOptions<E, O> &\n\tPick<\n\t\tRules,\n\t\t| \"min\"\n\t\t| \"max\"\n\t\t| \"length\"\n\t\t| \"regex\"\n\t\t| \"email\"\n\t\t| \"url\"\n\t\t| \"startsWith\"\n\t\t| \"endsWith\"\n\t\t| \"check\"\n\t> & { enum?: readonly E[] };\n\ntype ArrayOptions<E, O> = TypeOptions<FieldOut<E>[], O> &\n\tPick<Rules, \"min\" | \"max\" | \"length\" | \"check\">;\n\ntype NumberOptions<O> = TypeOptions<number, O> &\n\tPick<Rules, \"min\" | \"max\" | \"int\" | \"check\"> & {\n\t\tenum?: readonly number[];\n\t};\n\nexport type InferType<T> =\n\tT extends TypeDefination<infer T2, any, any> ? T2 : never;\n\nexport type InferOutput<T> =\n\tT extends TypeDefination<any, infer O, any> ? O : never;\n\nexport type DefineInput<I> = Prettify<{\n\t[K in keyof I]: FieldIn<I[K]>;\n}>;\n\n/** Keys whose field is OPTIONAL with no default: absent from the output\n * too, so they mark `?`. A defaulted field always produces a value and\n * stays required. */\ntype OutOptional<O> = {\n\t[K in keyof O]: [DefaultOf<O[K]>] extends [never]\n\t\t? never\n\t\t: [DefaultOf<O[K]>] extends [undefined]\n\t\t\t? K\n\t\t\t: never;\n}[keyof O];\n\nexport type DefineOutput<O> = Prettify<\n\t{ [K in keyof O as K extends OutOptional<O> ? never : K]: FieldOut<O[K]> } & {\n\t\t[K in keyof O as K extends OutOptional<O> ? K : never]?: FieldOut<O[K]>;\n\t}\n>;\n\n/**\n * A handler-less `v.fn({ input, output })` used as a schema describes\n * \"a fn from `input` to `output`\" - the VALUE is the fn itself. Two\n * views of the same signature:\n *\n * `SchemaFnIn` is the PROVIDER's side - what a caller must hand over.\n * Like any handler, their fn receives the PARSED input (validation runs\n * at its door) and returns the declared output, sync or async.\n *\n * `SchemaFnOut` is the CONSUMER's side (`c.input.x`) - the handler calls\n * it with RAW args, exactly like calling the fn it stands in for.\n *\n * No declared input means the signature is UNSPECIFIED, not zero-arg -\n * any fn fits (`create: v.fn`), so the args stay open.\n */\ntype SchemaFnIn<FI, FO> = (\n\t...args: unknown extends FI ? any[] : [input: InferInput<FI>]\n) => unknown extends FO\n\t? any\n\t: InferInput<OutputSchemaOf<FO>> | Promise<InferInput<OutputSchemaOf<FO>>>;\n\ntype SchemaFnOut<FI, FO> = (\n\t...args: unknown extends FI ? any[] : [input: InferArgs<FI>]\n) => unknown extends FO\n\t? any\n\t: InferInput<OutputSchemaOf<FO>> | Promise<InferInput<OutputSchemaOf<FO>>>;\n\n/**\n * A fn schema whose input IS a var carries that var's name as an optional\n * phantom (`$fnVar`, tuple-wrapped so a plain fn can never false-match).\n * Scope resolution reads it to WIDEN the fn's args with everything the\n * scope mounts on that var - see `WidenSchemaFns`. Optional, so any plain\n * closure still satisfies the type.\n */\nexport type FnVarBrand<FI> = FI extends {\n\t$var: true;\n\tname: infer N extends string;\n}\n\t? { readonly $fnVar?: [N] }\n\t: unknown;\n\n/**\n * A declared `output` comes in two forms: a bare schema (the signature\n * AND the exit check), or the wrapper `{ def?, validation? }` splitting\n * what the fn PROMISES from what gets CHECKED - `{ def }` documents\n * without paying runtime validation, `{ def, validation }` checks with a\n * different (usually looser) schema than it documents. The wrapper is\n * recognized by its keys, so an output that IS an object with only\n * `def`/`validation` fields must be written `v.object({...})`.\n *\n * `OutputSchemaOf` is the type-level unwrap - the schema the fn's return\n * type (and its rendered signature) comes from.\n */\nexport type OutputSchemaOf<O> =\n\tExclude<keyof O, \"def\" | \"validation\"> extends never\n\t\t? O extends { def: infer D }\n\t\t\t? D\n\t\t\t: O extends { validation: infer Vl }\n\t\t\t\t? Vl\n\t\t\t\t: O\n\t\t: O;\n\n/** The runtime unwrap: `def` is the documented schema (falls back to\n * `validation`), `validation` is what the exit check runs - undefined\n * means no check. A bare schema is both. */\nexport const outputContract = (\n\toutput: unknown,\n): { def?: unknown; validation?: unknown } => {\n\tif (output === undefined) return {};\n\tif (\n\t\toutput !== null &&\n\t\ttypeof output === \"object\" &&\n\t\t!Array.isArray(output) &&\n\t\t!isType(output) &&\n\t\t!isVar(output) &&\n\t\t!isFnSchema(output)\n\t) {\n\t\tconst keys = Object.keys(output);\n\t\tif (\n\t\t\tkeys.length > 0 &&\n\t\t\tkeys.every((k) => k === \"def\" || k === \"validation\")\n\t\t) {\n\t\t\tconst { def, validation } = output as {\n\t\t\t\tdef?: unknown;\n\t\t\t\tvalidation?: unknown;\n\t\t\t};\n\t\t\treturn { def: def ?? validation, validation };\n\t\t}\n\t}\n\treturn { def: output, validation: output };\n};\n\n/**\n * One input field, in four flavours:\n *  - a `v.var()`, whose shape comes from the var's own `schema`\n *  - a handler-less `v.fn(...)` builder, which types the field as a FN\n *  - a type from `v.string()` / `v.object()` / ...\n *  - a bare nested record, which recurses\n *\n * The record case has to come last: a TypeDefination is itself a record,\n * and so is a builder.\n */\ntype FieldOut<F> = F extends { $var: true; schema?: infer S }\n\t? InferInput<NonNullable<S>>\n\t: F extends { $fnSchema: { input?: infer FI; output?: infer FO } }\n\t\t? SchemaFnOut<FI, FO> & FnVarBrand<FI>\n\t\t: F extends TypeDefination<any, infer O, any>\n\t\t\t? O\n\t\t\t: F extends Record<string, unknown>\n\t\t\t\t? Prettify<{ [K in keyof F]: FieldOut<F[K]> }>\n\t\t\t\t: never;\n\ntype FieldIn<F> = F extends { $var: true; schema?: infer S }\n\t? InferArgs<NonNullable<S>>\n\t: F extends { $fnSchema: { input?: infer FI; output?: infer FO } }\n\t\t? SchemaFnIn<FI, FO> & FnVarBrand<FI>\n\t\t: F extends TypeDefination<infer T, any, any>\n\t\t\t? T\n\t\t\t: F extends Record<string, unknown>\n\t\t\t\t? ArgsShape<F>\n\t\t\t\t: never;\n\n/**\n * A field's declared default, looked through a var to its schema. Only a\n * TYPE's default counts - a var's own default is its initial value, not a\n * licence to omit the input. The `$fnSchema` guard mirrors `asType`'s\n * ordering: a bare `v.fn` is CALLABLE, and any callable duck-matches\n * TypeDefination (`.name` comes with every function), which would read a\n * phantom default off it and wrongly mark the field optional.\n */\ntype DefaultOf<F> = F extends { $var: true; schema?: infer S }\n\t? NonNullable<S> extends TypeDefination<any, any, infer D>\n\t\t? D\n\t\t: never\n\t: F extends { $fnSchema: unknown }\n\t\t? never\n\t\t: F extends TypeDefination<any, any, infer D>\n\t\t\t? D\n\t\t\t: never;\n\ntype Defaulted<I> = {\n\t[K in keyof I]: [DefaultOf<I[K]>] extends [never] ? never : K;\n}[keyof I];\n\n/** Defaulted keys are optional to send, but always present in the handler. */\ntype ArgsShape<I> = Prettify<\n\t{ [K in keyof I as K extends Defaulted<I> ? never : K]: FieldIn<I[K]> } & {\n\t\t[K in keyof I as K extends Defaulted<I> ? K : never]?: FieldIn<I[K]>;\n\t}\n>;\n\n/**\n * Post-transform shape - what a handler sees. The `$var` branch must come\n * first: a var's `name` property duck-matches TypeDefination, and falling\n * into that branch reads the var's VALUE type instead of its schema. A\n * TUPLE input maps position by position - the fn takes that many args.\n */\nexport type InferInput<I> = I extends { $var: true; schema?: infer S }\n\t? InferInput<NonNullable<S>>\n\t: I extends { $fnSchema: { input?: infer FI; output?: infer FO } }\n\t\t? SchemaFnOut<FI, FO> & FnVarBrand<FI>\n\t\t: I extends readonly unknown[]\n\t\t\t? { -readonly [K in keyof I]: InferInput<I[K]> }\n\t\t\t: I extends TypeDefination<any, infer O, any>\n\t\t\t\t? O\n\t\t\t\t: Prettify<{ [K in keyof I]: FieldOut<I[K]> }>;\n\n/** Pre-transform shape - what a caller sends. Same branch order. */\nexport type InferArgs<I> = I extends { $var: true; schema?: infer S }\n\t? InferArgs<NonNullable<S>>\n\t: I extends { $fnSchema: { input?: infer FI; output?: infer FO } }\n\t\t? SchemaFnIn<FI, FO> & FnVarBrand<FI>\n\t\t: I extends readonly unknown[]\n\t\t\t? { -readonly [K in keyof I]: InferArgs<I[K]> }\n\t\t\t: I extends TypeDefination<infer T, any, any>\n\t\t\t\t? T\n\t\t\t\t: ArgsShape<I>;\n\nexport const isType = (value: any): value is TypeDefination<any, any> =>\n\ttypeof value?.name === \"string\";\n\n/** A handler-less `v.fn(...)` builder doubles as a schema: the value it\n * describes is a FN with the declared signature. The builder FN itself is\n * branded too, so bare `v.fn` reads as \"any function\". */\nexport const isFnSchema = (\n\tvalue: any,\n): value is { $fnSchema: { input?: unknown; output?: unknown } } =>\n\ttypeof value?.$fnSchema === \"object\" && value.$fnSchema !== null;\n\nexport const asType = (value: any): TypeDefination<any, any> =>\n\t// A var's own `name` (\"user\") would duck-match isType, so unwrap first -\n\t// and a builder is a record, so it must be caught before the fallback.\n\tisVar(value)\n\t\t? asType(value.schema ?? {})\n\t\t: isFnSchema(value)\n\t\t\t? { name: \"function\", fnInput: value.$fnSchema.input }\n\t\t\t: isType(value)\n\t\t\t\t? value\n\t\t\t\t: { name: \"object\", shape: value };\n\nexport const typeOf = (value: unknown) =>\n\tvalue === null\n\t\t? \"null\"\n\t\t: Array.isArray(value)\n\t\t\t? \"array\"\n\t\t\t: Number.isNaN(value)\n\t\t\t\t? \"NaN\"\n\t\t\t\t: typeof value;\n\nexport const isVar = (value: any): boolean => value?.$var === true;\n\nconst EMAIL = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\nconst fail = (path: string, message: string): never => {\n\tthrow new ValidationError(path, message);\n};\n\n/** Constraint checks, run after the value's type is known to be right. */\nconst applyRules = (def: Rules, value: any, path: string) => {\n\tif (def.enum && !def.enum.includes(value)) {\n\t\tfail(path, `expected one of ${def.enum.join(\", \")}, received ${value}`);\n\t}\n\tif (typeof value === \"string\") {\n\t\tif (def.length !== undefined && value.length !== def.length) {\n\t\t\tfail(path, `expected length ${def.length}, received ${value.length}`);\n\t\t}\n\t\tif (def.min !== undefined && value.length < def.min) {\n\t\t\tfail(\n\t\t\t\tpath,\n\t\t\t\t`expected at least ${def.min} characters, received ${value.length}`,\n\t\t\t);\n\t\t}\n\t\tif (def.max !== undefined && value.length > def.max) {\n\t\t\tfail(\n\t\t\t\tpath,\n\t\t\t\t`expected at most ${def.max} characters, received ${value.length}`,\n\t\t\t);\n\t\t}\n\t\tif (def.regex && !def.regex.test(value)) {\n\t\t\tfail(path, `does not match ${def.regex}`);\n\t\t}\n\t\tif (def.email && !EMAIL.test(value))\n\t\t\tfail(path, \"expected an email address\");\n\t\tif (def.url) {\n\t\t\ttry {\n\t\t\t\tnew URL(value);\n\t\t\t} catch {\n\t\t\t\tfail(path, \"expected a URL\");\n\t\t\t}\n\t\t}\n\t\tif (def.startsWith !== undefined && !value.startsWith(def.startsWith)) {\n\t\t\tfail(path, `expected to start with \"${def.startsWith}\"`);\n\t\t}\n\t\tif (def.endsWith !== undefined && !value.endsWith(def.endsWith)) {\n\t\t\tfail(path, `expected to end with \"${def.endsWith}\"`);\n\t\t}\n\t}\n\tif (Array.isArray(value)) {\n\t\tif (def.length !== undefined && value.length !== def.length) {\n\t\t\tfail(path, `expected length ${def.length}, received ${value.length}`);\n\t\t}\n\t\tif (def.min !== undefined && value.length < def.min) {\n\t\t\tfail(\n\t\t\t\tpath,\n\t\t\t\t`expected at least ${def.min} items, received ${value.length}`,\n\t\t\t);\n\t\t}\n\t\tif (def.max !== undefined && value.length > def.max) {\n\t\t\tfail(path, `expected at most ${def.max} items, received ${value.length}`);\n\t\t}\n\t}\n\tif (typeof value === \"number\") {\n\t\tif (def.int && !Number.isInteger(value)) {\n\t\t\tfail(path, `expected an integer, received ${value}`);\n\t\t}\n\t\tif (def.min !== undefined && value < def.min) {\n\t\t\tfail(path, `expected >= ${def.min}, received ${value}`);\n\t\t}\n\t\tif (def.max !== undefined && value > def.max) {\n\t\t\tfail(path, `expected <= ${def.max}, received ${value}`);\n\t\t}\n\t}\n\tif (def.check) {\n\t\tconst result = def.check(value);\n\t\tif (result !== true) {\n\t\t\tfail(path, typeof result === \"string\" ? result : \"failed check\");\n\t\t}\n\t}\n};\n\nexport const validate = (\n\tdef: TypeDefination<any, any, any>,\n\tvalue: unknown,\n\tpath: string,\n): any => {\n\t// `undefined` falls back to the declared default before anything else,\n\t// then to `optional`, which passes it through untouched.\n\tif (value === undefined) {\n\t\tif (def.default !== undefined) value = def.default;\n\t\telse if (def.optional) return undefined;\n\t}\n\t// A var used as an input field validates against its own schema. An\n\t// absent value is left alone so the var keeps its default.\n\tif (isVar(def)) {\n\t\tif (value === undefined) return undefined;\n\t\tconst schema = (def as any).schema;\n\t\treturn schema === undefined ? value : validate(schema, value, path);\n\t}\n\tif (def.name === \"any\") {\n\t\treturn def.transform ? def.transform(value) : value;\n\t}\n\tif (def.name === \"date\") {\n\t\tif (!(value instanceof Date)) {\n\t\t\tthrow new ValidationError(\n\t\t\t\tpath,\n\t\t\t\t`expected date, received ${typeOf(value)}`,\n\t\t\t);\n\t\t}\n\t\treturn def.transform ? def.transform(value) : value;\n\t}\n\tif (def.name === \"function\") {\n\t\tif (typeof value !== \"function\") {\n\t\t\tthrow new ValidationError(\n\t\t\t\tpath,\n\t\t\t\t`expected function, received ${typeOf(value)}`,\n\t\t\t);\n\t\t}\n\t\t// A branded fn (`$fn`) validates its own declared input at its own\n\t\t// door; a plain closure gets THIS schema's input validated for it.\n\t\tconst inner = def.fnInput;\n\t\tif (inner === undefined || (value as { $fn?: boolean }).$fn === true) {\n\t\t\treturn value;\n\t\t}\n\t\tconst innerType = asType(inner);\n\t\treturn (input?: unknown, parent?: unknown) =>\n\t\t\t(value as (i: unknown, p: unknown) => unknown)(\n\t\t\t\tvalidate(innerType, input, `${path}()`),\n\t\t\t\tparent,\n\t\t\t);\n\t}\n\tif (def.name === \"array\") {\n\t\tif (!Array.isArray(value)) {\n\t\t\tthrow new ValidationError(\n\t\t\t\tpath,\n\t\t\t\t`expected array, received ${typeOf(value)}`,\n\t\t\t);\n\t\t}\n\t\tapplyRules(def, value, path);\n\t\t// No declared element (`v.array()`): ANY array - passed through\n\t\t// as-is, elements untouched.\n\t\tif (def.shape === undefined) {\n\t\t\treturn def.transform ? def.transform(value) : value;\n\t\t}\n\t\t// Every element validates - ALL failures report together, not\n\t\t// just the first, mirroring object fields.\n\t\tconst elementType = asType(def.shape);\n\t\tconst items: unknown[] = [];\n\t\tconst problems: Issue[] = [];\n\t\tfor (let index = 0; index < value.length; index++) {\n\t\t\ttry {\n\t\t\t\titems.push(validate(elementType, value[index], `${path}[${index}]`));\n\t\t\t} catch (thrown) {\n\t\t\t\tif (!(thrown instanceof ValidationError)) throw thrown;\n\t\t\t\tproblems.push(...thrown.issues);\n\t\t\t}\n\t\t}\n\t\tconst firstProblem = problems[0];\n\t\tif (firstProblem) {\n\t\t\tthrow new ValidationError(\n\t\t\t\tfirstProblem.path,\n\t\t\t\tfirstProblem.message,\n\t\t\t\tproblems,\n\t\t\t);\n\t\t}\n\t\treturn def.transform ? def.transform(items) : items;\n\t}\n\tif (def.name === \"object\") {\n\t\tif (typeOf(value) !== \"object\") {\n\t\t\tthrow new ValidationError(\n\t\t\t\tpath,\n\t\t\t\t`expected object, received ${typeOf(value)}`,\n\t\t\t);\n\t\t}\n\t\t// No declared shape (`v.object()`): ANY object - passed through\n\t\t// as-is, nothing stripped.\n\t\tif (def.shape === undefined) {\n\t\t\treturn def.transform ? def.transform(value) : value;\n\t\t}\n\t\t// Every field validates - ALL failures report together, not just\n\t\t// the first. Three bad fields is one error with three issues.\n\t\tconst parsed: Record<string, unknown> = {};\n\t\tconst issues: Issue[] = [];\n\t\tfor (const [field, child] of Object.entries(\n\t\t\tdef.shape as Record<string, unknown>,\n\t\t)) {\n\t\t\ttry {\n\t\t\t\tconst parsedField = validate(\n\t\t\t\t\tasType(child),\n\t\t\t\t\t(value as Record<string, unknown>)[field],\n\t\t\t\t\t`${path}.${field}`,\n\t\t\t\t);\n\t\t\t\t// An absent optional field stays ABSENT - materializing the key\n\t\t\t\t// as `undefined` would clobber values it gets spread over.\n\t\t\t\tif (parsedField !== undefined) parsed[field] = parsedField;\n\t\t\t} catch (thrown) {\n\t\t\t\tif (!(thrown instanceof ValidationError)) throw thrown;\n\t\t\t\tissues.push(...thrown.issues);\n\t\t\t}\n\t\t}\n\t\tconst firstIssue = issues[0];\n\t\tif (firstIssue) {\n\t\t\tthrow new ValidationError(firstIssue.path, firstIssue.message, issues);\n\t\t}\n\t\treturn def.transform ? def.transform(parsed) : parsed;\n\t}\n\tif (typeOf(value) !== def.name) {\n\t\tthrow new ValidationError(\n\t\t\tpath,\n\t\t\t`expected ${def.name}, received ${typeOf(value)}`,\n\t\t);\n\t}\n\tapplyRules(def, value, path);\n\treturn def.transform ? def.transform(value) : value;\n};\n\n/** Builds the runtime object; the declared return type is the contract. */\nconst build = (name: string, options: any, extra?: any): any => ({\n\tname,\n\t...extra,\n\t...options,\n});\n\nexport const vTypes = {\n\t/** An `enum` narrows both sides to the literal union: `v.string({\n\t * enum: [\"a\", \"b\"] })` types as `\"a\" | \"b\"`, not `string`. */\n\tstring: <\n\t\tconst E extends string = string,\n\t\tO = E,\n\t\tD = never,\n\t\tOpt extends boolean = false,\n\t>(\n\t\toptions?: StringOptions<E, O> & WithDefault<D> & WithOptional<Opt>,\n\t): TypeDefination<E, OutOf<O, D, Opt>, DefOf<D, Opt>> =>\n\t\tbuild(\"string\", options),\n\tnumber: <O = number, D = never, Opt extends boolean = false>(\n\t\toptions?: NumberOptions<O> & WithDefault<D> & WithOptional<Opt>,\n\t): TypeDefination<number, OutOf<O, D, Opt>, DefOf<D, Opt>> =>\n\t\tbuild(\"number\", options),\n\tboolean: <O = boolean, D = never, Opt extends boolean = false>(\n\t\toptions?: TypeOptions<boolean, O> & WithDefault<D> & WithOptional<Opt>,\n\t): TypeDefination<boolean, OutOf<O, D, Opt>, DefOf<D, Opt>> =>\n\t\tbuild(\"boolean\", options),\n\t/** A Date INSTANCE - checked with `instanceof`, never parsed. */\n\tdate: <O = Date, D = never, Opt extends boolean = false>(\n\t\toptions?: TypeOptions<Date, O> & WithDefault<D> & WithOptional<Opt>,\n\t): TypeDefination<Date, OutOf<O, D, Opt>, DefOf<D, Opt>> =>\n\t\tbuild(\"date\", options),\n\t/** Passthrough - validated as-is, never coerced or stripped. */\n\tany: <T = unknown, D = never, Opt extends boolean = false>(\n\t\toptions?: TypeOptions<T, T> & WithDefault<D> & WithOptional<Opt>,\n\t): TypeDefination<T, OutOf<T, D, Opt>, DefOf<D, Opt>> =>\n\t\tbuild(\"any\", options),\n\t/** With a SHAPE every field validates; with NO shape (`v.object()`)\n\t * any object passes, as-is. */\n\tobject: <\n\t\tS = undefined,\n\t\tO = DefineOutput<S>,\n\t\tD = never,\n\t\tOpt extends boolean = false,\n\t>(\n\t\tshape?: S,\n\t\toptions?: TypeOptions<DefineOutput<S>, O> &\n\t\t\tWithDefault<D> &\n\t\t\tWithOptional<Opt>,\n\t\t// Args use ArgsShape, not DefineInput, so a defaulted field inside\n\t\t// an object is optional to send there too.\n\t): [S] extends [undefined]\n\t\t? TypeDefination<Record<string, any>, Record<string, any>>\n\t\t: TypeDefination<ArgsShape<S>, OutOf<O, D, Opt>, DefOf<D, Opt>> =>\n\t\tbuild(\"object\", options, shape === undefined ? {} : { shape }),\n\t/** With an ELEMENT every item validates - all failures report\n\t * together, like object fields; with NO element (`v.array()`) any\n\t * array passes, as-is. `min`/`max`/`length` count items. */\n\tarray: <\n\t\tE = undefined,\n\t\tO = FieldOut<E>[],\n\t\tD = never,\n\t\tOpt extends boolean = false,\n\t>(\n\t\telement?: E,\n\t\toptions?: ArrayOptions<E, O> & WithDefault<D> & WithOptional<Opt>,\n\t): [E] extends [undefined]\n\t\t? TypeDefination<any[], OutOf<any[], D, Opt>, DefOf<D, Opt>>\n\t\t: TypeDefination<FieldIn<E>[], OutOf<O, D, Opt>, DefOf<D, Opt>> =>\n\t\tbuild(\"array\", options, element === undefined ? {} : { shape: element }),\n} satisfies Record<string, (...args: any[]) => TypeDefination<any, any>>;\n"],"mappings":"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"}

package/dist/scope.d.cts

@@ -0,0 +1,18 @@
+import { Prettify } from "./types.cjs";
+import { ModuleVars, VarArgsInScope, VarExtensionsFor } from "./module.cjs";
+//#region src/scope.d.ts
+type MergeExtension<T, E> = T extends object ? Prettify<T & E> : T;
+type Merged<PL, Base> = ModuleVars<PL> & Base;
+type WidenSchemaFn<T, PL> = T extends {
+  $fnVar?: [infer N extends string];
+} ? T extends ((input: infer A) => infer R) ? unknown extends VarArgsInScope<PL, N> ? T : ((input: Prettify<A & VarArgsInScope<PL, N>>) => R) & {
+  readonly $fnVar?: [N];
+} : T : T;
+type WidenSchemaFns<T, PL> = T extends ((...args: any[]) => any) ? WidenSchemaFn<T, PL> : T extends readonly unknown[] ? { [K in keyof T]: WidenSchemaFns<T[K], PL>; } : T extends Date | RegExp | Promise<unknown> | Map<any, any> | Set<any> ? T : T extends object ? { [K in keyof T]: WidenSchemaFns<T[K], PL>; } : T;
+type ScopeOf<PL, Base = unknown, ExtPL = PL> = { [K in keyof Merged<PL, Base>]: WidenSchemaFns<MergeExtension<Merged<PL, Base>[K], VarExtensionsFor<ExtPL, K & string>>, ExtPL>; };
+type ResolvedVars<PL> = { [K in keyof ModuleVars<PL>]: MergeExtension<ModuleVars<PL>[K], VarExtensionsFor<PL, K & string>>; };
+type VarScope<RV, Required, RO extends boolean = false> = RO extends true ? { readonly [K in keyof RV]: K extends Required ? NonNullable<RV[K]> : RV[K]; } : Prettify<{ [K in keyof RV]: K extends Required ? NonNullable<RV[K]> : RV[K]; }>;
+type VarName<RV> = keyof RV & string;
+//#endregion
+export { ResolvedVars, ScopeOf, VarName, VarScope, WidenSchemaFns };
+//# sourceMappingURL=scope.d.cts.map

package/dist/scope.d.mts

@@ -0,0 +1,18 @@
+import { Prettify } from "./types.mjs";
+import { ModuleVars, VarArgsInScope, VarExtensionsFor } from "./module.mjs";
+//#region src/scope.d.ts
+type MergeExtension<T, E> = T extends object ? Prettify<T & E> : T;
+type Merged<PL, Base> = ModuleVars<PL> & Base;
+type WidenSchemaFn<T, PL> = T extends {
+  $fnVar?: [infer N extends string];
+} ? T extends ((input: infer A) => infer R) ? unknown extends VarArgsInScope<PL, N> ? T : ((input: Prettify<A & VarArgsInScope<PL, N>>) => R) & {
+  readonly $fnVar?: [N];
+} : T : T;
+type WidenSchemaFns<T, PL> = T extends ((...args: any[]) => any) ? WidenSchemaFn<T, PL> : T extends readonly unknown[] ? { [K in keyof T]: WidenSchemaFns<T[K], PL>; } : T extends Date | RegExp | Promise<unknown> | Map<any, any> | Set<any> ? T : T extends object ? { [K in keyof T]: WidenSchemaFns<T[K], PL>; } : T;
+type ScopeOf<PL, Base = unknown, ExtPL = PL> = { [K in keyof Merged<PL, Base>]: WidenSchemaFns<MergeExtension<Merged<PL, Base>[K], VarExtensionsFor<ExtPL, K & string>>, ExtPL>; };
+type ResolvedVars<PL> = { [K in keyof ModuleVars<PL>]: MergeExtension<ModuleVars<PL>[K], VarExtensionsFor<PL, K & string>>; };
+type VarScope<RV, Required, RO extends boolean = false> = RO extends true ? { readonly [K in keyof RV]: K extends Required ? NonNullable<RV[K]> : RV[K]; } : Prettify<{ [K in keyof RV]: K extends Required ? NonNullable<RV[K]> : RV[K]; }>;
+type VarName<RV> = keyof RV & string;
+//#endregion
+export { ResolvedVars, ScopeOf, VarName, VarScope, WidenSchemaFns };
+//# sourceMappingURL=scope.d.mts.map

package/dist/storage.cjs

@@ -0,0 +1,256 @@
+const require_schema = require("./schema.cjs");
+const require_module = require("./module.cjs");
+//#region src/storage.ts
+const WHERE_OPS = {
+	eq: true,
+	ne: true,
+	lt: true,
+	lte: true,
+	gt: true,
+	gte: true,
+	in: true,
+	notIn: true,
+	contains: true,
+	startsWith: true,
+	endsWith: true
+};
+/** An operator object is a plain record whose keys are ALL operator names.
+* Anything else - a Date, an array, an empty object - is a value. */
+const isOps = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date) && Object.keys(value).length > 0 && Object.keys(value).every((key) => key in WHERE_OPS);
+/** Flatten a where to normalized conditions - the adapter author's
+* translation seam: map each condition onto your query language, AND them. */
+const conditionsOf = (where = {}) => Object.entries(where).flatMap(([field, spec]) => isOps(spec) ? Object.entries(spec).map(([op, value]) => ({
+	field,
+	op,
+	value
+})) : [{
+	field,
+	op: "eq",
+	value: spec
+}]);
+/** Dates equate and order by their instant. */
+const rawValue = (value) => value instanceof Date ? value.getTime() : value;
+const equals = (a, b) => rawValue(a) === rawValue(b);
+const compare = (a, b) => {
+	const left = rawValue(a);
+	const right = rawValue(b);
+	return left < right ? -1 : left > right ? 1 : 0;
+};
+const holds = (row, { field, op, value }) => {
+	const current = row[field];
+	switch (op) {
+		case "eq": return equals(current, value);
+		case "ne": return !equals(current, value);
+		case "lt":
+		case "lte":
+		case "gt":
+		case "gte": {
+			if (current == null || value == null) return false;
+			const order = compare(current, value);
+			if (op === "lt") return order < 0;
+			if (op === "lte") return order <= 0;
+			if (op === "gt") return order > 0;
+			return order >= 0;
+		}
+		case "in": return value.some((member) => equals(current, member));
+		case "notIn": return !value.some((member) => equals(current, member));
+		case "contains": return typeof current === "string" && current.includes(value);
+		case "startsWith": return typeof current === "string" && current.startsWith(value);
+		case "endsWith": return typeof current === "string" && current.endsWith(value);
+	}
+};
+/** 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. */
+const matchesWhere = (row, where = {}) => conditionsOf(where).every((condition) => holds(row, condition));
+/** 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. */
+const memoryAdapter = () => {
+	let tables = /* @__PURE__ */ new Map();
+	const rows = (model) => {
+		let list = tables.get(model);
+		if (!list) {
+			list = [];
+			tables.set(model, list);
+		}
+		return list;
+	};
+	const self = {
+		create: (model, data) => {
+			const row = { ...data };
+			rows(model).push(row);
+			return row;
+		},
+		findOne: (model, where) => rows(model).find((row) => matchesWhere(row, where)) ?? null,
+		findMany: (model, where, options) => {
+			let list = rows(model).filter((row) => matchesWhere(row, where));
+			const sort = options?.sortBy;
+			if (sort) {
+				const direction = sort.direction === "desc" ? -1 : 1;
+				list = [...list].sort((a, b) => direction * compare(a[sort.field], b[sort.field]));
+			}
+			const start = options?.offset ?? 0;
+			const end = options?.limit === void 0 ? void 0 : start + options.limit;
+			return start === 0 && end === void 0 ? list : list.slice(start, end);
+		},
+		update: (model, where, patch) => {
+			const row = rows(model).find((r) => matchesWhere(r, where));
+			return row ? Object.assign(row, patch) : null;
+		},
+		delete: (model, where) => {
+			const list = rows(model);
+			const keep = list.filter((row) => !matchesWhere(row, where));
+			tables.set(model, keep);
+			return list.length - keep.length;
+		},
+		count: (model, where) => rows(model).filter((row) => matchesWhere(row, where)).length,
+		consumeOne: (model, where) => {
+			const list = rows(model);
+			const index = list.findIndex((row) => matchesWhere(row, where));
+			return index === -1 ? null : list.splice(index, 1)[0];
+		},
+		incrementOne: (model, where, increments) => {
+			const row = rows(model).find((r) => matchesWhere(r, where));
+			if (!row) return null;
+			for (const [field, by] of Object.entries(increments)) row[field] = (row[field] ?? 0) + by;
+			return row;
+		},
+		transaction: async (run) => {
+			const snapshot = new Map([...tables].map(([model, list]) => [model, list.map((row) => ({ ...row }))]));
+			try {
+				return await run(self);
+			} catch (thrown) {
+				tables = snapshot;
+				throw thrown;
+			}
+		}
+	};
+	return self;
+};
+const OPS = [
+	"create",
+	"findOne",
+	"findMany",
+	"update",
+	"delete",
+	"count",
+	"consumeOne",
+	"incrementOne"
+];
+/** The op against the backend, optional verbs falling back to the required
+* six: find-then-write - correct alone, racy under contention. The comment
+* every fallback deserves lives on `StorageAdapter`. */
+const rawOp = (adapter, name, op, args) => {
+	if (op === "consumeOne" && !adapter.consumeOne) return (async () => {
+		const where = args[0];
+		const row = await adapter.findOne(name, where);
+		if (!row) return null;
+		await adapter.delete(name, row);
+		return row;
+	})();
+	if (op === "incrementOne" && !adapter.incrementOne) return (async () => {
+		const [where, increments] = args;
+		const row = await adapter.findOne(name, where);
+		if (!row) return null;
+		const patch = Object.fromEntries(Object.entries(increments).map(([field, by]) => [field, (row[field] ?? 0) + by]));
+		return adapter.update(name, where, patch);
+	})();
+	return adapter[op](name, ...args);
+};
+const buildStorage = (state, models) => {
+	const run = (key, name, op, args) => {
+		const base = () => Promise.resolve(rawOp(state.adapter, name, op, args));
+		return state.hooks.filter((entry) => require_module.matchesTarget(entry.target, `${key}.${op}`)).reduceRight((next, entry) => () => Promise.resolve(entry.hook({
+			model: key,
+			op,
+			args
+		}, next)), base)();
+	};
+	const storage = {};
+	for (const [key, input] of Object.entries(models)) {
+		const name = (require_schema.isVar(input) ? input : input.schema).name;
+		const collection = {
+			create: (data) => run(key, name, "create", [data]),
+			findOne: (where) => run(key, name, "findOne", [where]),
+			findMany: (where, options) => run(key, name, "findMany", [where, options]),
+			update: (where, patch) => run(key, name, "update", [where, patch]),
+			delete: (where) => run(key, name, "delete", [where]),
+			count: (where) => run(key, name, "count", [where]),
+			consumeOne: (where) => run(key, name, "consumeOne", [where]),
+			incrementOne: (where, increments) => run(key, name, "incrementOne", [where, increments])
+		};
+		storage[key] = collection;
+		if (require_schema.isVar(input)) continue;
+		for (const op of OPS) {
+			const declared = input[op];
+			if (!declared) continue;
+			const cacheKey = `${key}.${op}`;
+			let entries = state.subscriptions.get(cacheKey);
+			if (!entries) {
+				const produced = typeof declared === "function" ? declared(collection[op]) : declared;
+				entries = Array.isArray(produced) ? produced : [produced];
+				state.subscriptions.set(cacheKey, entries);
+			}
+			entries.forEach((entry, index) => {
+				storage[`${key}$${op}${index === 0 ? "" : index}`] = entry;
+			});
+		}
+	}
+	const self = Object.assign(storage, {
+		$adapter: (adapter) => {
+			state.adapter = adapter;
+			return self;
+		},
+		$on: (target, hook) => {
+			state.hooks.push({
+				target,
+				hook
+			});
+			return self;
+		},
+		$omit: (...keys) => buildStorage(state, Object.fromEntries(Object.entries(models).filter(([key]) => !keys.includes(key)))),
+		$pick: (...keys) => buildStorage(state, Object.fromEntries(keys.map((key) => [key, models[key]]))),
+		$extend: (more) => buildStorage(state, {
+			...models,
+			...more
+		}),
+		$transaction: (fn) => {
+			const inside = (adapter) => Promise.resolve(fn(buildStorage({
+				...state,
+				adapter
+			}, models)));
+			return state.adapter.transaction ? state.adapter.transaction((tx) => inside(tx)) : inside(state.adapter);
+		},
+		$models: models
+	});
+	return self;
+};
+/**
+* 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.
+*/
+const makeStorage = (adapter, models) => buildStorage({
+	adapter,
+	hooks: [],
+	subscriptions: /* @__PURE__ */ new Map()
+}, models);
+//#endregion
+exports.conditionsOf = conditionsOf;
+exports.makeStorage = makeStorage;
+exports.matchesWhere = matchesWhere;
+exports.memoryAdapter = memoryAdapter;
+
+//# sourceMappingURL=storage.cjs.map

package/dist/storage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.cjs","names":["matchesTarget","isVar"],"sources":["../src/storage.ts"],"sourcesContent":["import { matchesTarget, type OnEntry } from \"./module\";\nimport { isVar } from \"./schema\";\nimport type { ValueOfVar, VarDefination } from \"./var\";\n\n/* ---------------------------------- where ---------------------------------- */\n\n/** Per-field operators, for everything equality can't say: expiry sweeps\n * (`lt`), revocation lists (`in`), guarded counters (`lt` as the guard).\n * A bare value stays plain equality - the common case reads like data. */\nexport type WhereOps<V> = {\n\teq?: V;\n\tne?: V;\n\tlt?: V;\n\tlte?: V;\n\tgt?: V;\n\tgte?: V;\n\tin?: readonly V[];\n\tnotIn?: readonly V[];\n\tcontains?: string;\n\tstartsWith?: string;\n\tendsWith?: string;\n};\n\nexport type WhereOp = keyof WhereOps<unknown>;\n\n/** AND across fields; each field a bare value (equality) or operators. */\nexport type Where<R> = { [K in keyof R]?: R[K] | WhereOps<R[K]> };\n\n/** One normalized clause: `{ tag: \"a\" }` -> `{ field: \"tag\", op: \"eq\" }`. */\nexport type Condition = { field: string; op: WhereOp; value: unknown };\n\nconst WHERE_OPS: Record<WhereOp, true> = {\n\teq: true,\n\tne: true,\n\tlt: true,\n\tlte: true,\n\tgt: true,\n\tgte: true,\n\tin: true,\n\tnotIn: true,\n\tcontains: true,\n\tstartsWith: true,\n\tendsWith: true,\n};\n\n/** An operator object is a plain record whose keys are ALL operator names.\n * Anything else - a Date, an array, an empty object - is a value. */\nconst isOps = (value: unknown): value is WhereOps<unknown> =>\n\ttypeof value === \"object\" &&\n\tvalue !== null &&\n\t!Array.isArray(value) &&\n\t!(value instanceof Date) &&\n\tObject.keys(value).length > 0 &&\n\tObject.keys(value).every((key) => key in WHERE_OPS);\n\n/** Flatten a where to normalized conditions - the adapter author's\n * translation seam: map each condition onto your query language, AND them. */\nexport const conditionsOf = (\n\twhere: Record<string, unknown> = {},\n): Condition[] =>\n\tObject.entries(where).flatMap(([field, spec]) =>\n\t\tisOps(spec)\n\t\t\t? Object.entries(spec).map(([op, value]) => ({\n\t\t\t\t\tfield,\n\t\t\t\t\top: op as WhereOp,\n\t\t\t\t\tvalue,\n\t\t\t\t}))\n\t\t\t: [{ field, op: \"eq\" as const, value: spec }],\n\t);\n\n/** Dates equate and order by their instant. */\nconst rawValue = (value: unknown) =>\n\tvalue instanceof Date ? value.getTime() : value;\n\nconst equals = (a: unknown, b: unknown) => rawValue(a) === rawValue(b);\n\nconst compare = (a: unknown, b: unknown): number => {\n\tconst left = rawValue(a) as number;\n\tconst right = rawValue(b) as number;\n\treturn left < right ? -1 : left > right ? 1 : 0;\n};\n\nconst holds = (\n\trow: Record<string, unknown>,\n\t{ field, op, value }: Condition,\n): boolean => {\n\tconst current = row[field];\n\tswitch (op) {\n\t\tcase \"eq\":\n\t\t\treturn equals(current, value);\n\t\tcase \"ne\":\n\t\t\treturn !equals(current, value);\n\t\tcase \"lt\":\n\t\tcase \"lte\":\n\t\tcase \"gt\":\n\t\tcase \"gte\": {\n\t\t\tif (current == null || value == null) return false;\n\t\t\tconst order = compare(current, value);\n\t\t\tif (op === \"lt\") return order < 0;\n\t\t\tif (op === \"lte\") return order <= 0;\n\t\t\tif (op === \"gt\") return order > 0;\n\t\t\treturn order >= 0;\n\t\t}\n\t\tcase \"in\":\n\t\t\treturn (value as readonly unknown[]).some((member) =>\n\t\t\t\tequals(current, member),\n\t\t\t);\n\t\tcase \"notIn\":\n\t\t\treturn !(value as readonly unknown[]).some((member) =>\n\t\t\t\tequals(current, member),\n\t\t\t);\n\t\tcase \"contains\":\n\t\t\treturn typeof current === \"string\" && current.includes(value as string);\n\t\tcase \"startsWith\":\n\t\t\treturn typeof current === \"string\" && current.startsWith(value as string);\n\t\tcase \"endsWith\":\n\t\t\treturn typeof current === \"string\" && current.endsWith(value as string);\n\t}\n};\n\n/** Does a row satisfy a where? The in-memory evaluator - the dummy adapter\n * runs on it, and any adapter over an unqueryable backend can too. */\nexport const matchesWhere = (\n\trow: Record<string, unknown>,\n\twhere: Record<string, unknown> = {},\n): boolean => conditionsOf(where).every((condition) => holds(row, condition));\n\n/* ----------------------------------- ops ----------------------------------- */\n\n/** Shaping for `findMany`: sort, then window. */\nexport type FindManyOptions<R> = {\n\tlimit?: number;\n\toffset?: number;\n\tsortBy?: { field: keyof R & string; direction?: \"asc\" | \"desc\" };\n};\n\n/** One model's CRUD surface. `create` is generic so a row EXTENDED by a\n * mounted module (an account with a password field) keeps its extra\n * fields through the round-trip. */\nexport type Collection<R> = {\n\tcreate: <T extends R>(data: T) => Promise<T>;\n\tfindOne: (where: Where<R>) => Promise<R | null>;\n\tfindMany: (where?: Where<R>, options?: FindManyOptions<R>) => Promise<R[]>;\n\t/** Merge `patch` into the FIRST match - null when nothing matched. */\n\tupdate: (where: Where<R>, patch: Partial<R>) => Promise<R | null>;\n\t/** Remove every match; how many is the answer. */\n\tdelete: (where: Where<R>) => Promise<number>;\n\tcount: (where?: Where<R>) => Promise<number>;\n\t/** Claim the FIRST match: the row comes back and is GONE, atomically -\n\t * two racing consumers never both get it. Single-use credentials\n\t * (verification tokens, one-time codes) hang off this. */\n\tconsumeOne: (where: Where<R>) => Promise<R | null>;\n\t/** Add to numeric fields of the FIRST match, atomically; the where is\n\t * also the GUARD (`count: { lt: max }`), so check-and-bump is one op -\n\t * null means no row passed it. Rate limiting hangs off this. */\n\tincrementOne: (\n\t\twhere: Where<R>,\n\t\tincrements: Partial<Record<keyof R & string, number>>,\n\t) => Promise<R | null>;\n};\n\n/**\n * What a real database implements: six required verbs, models addressed by\n * NAME, `where` as bare-equality fields and/or operator objects\n * (`conditionsOf` normalizes either form). The storage API above never\n * changes - adapters translate it, sync or async.\n *\n * The optional verbs are ATOMICITY upgrades: without `consumeOne` /\n * `incrementOne` the storage falls back to find-then-write - correct alone,\n * racy under contention - and without `transaction` a `$transaction` block\n * runs plainly. Implement them where the backend has the primitive.\n */\nexport type StorageAdapter = {\n\tcreate: (model: string, data: Record<string, unknown>) => unknown;\n\tfindOne: (model: string, where: Record<string, unknown>) => unknown;\n\tfindMany: (\n\t\tmodel: string,\n\t\twhere?: Record<string, unknown>,\n\t\toptions?: FindManyOptions<Record<string, unknown>>,\n\t) => unknown;\n\tupdate: (\n\t\tmodel: string,\n\t\twhere: Record<string, unknown>,\n\t\tpatch: Record<string, unknown>,\n\t) => unknown;\n\tdelete: (model: string, where: Record<string, unknown>) => unknown;\n\tcount: (model: string, where?: Record<string, unknown>) => unknown;\n\t/** Atomic find-and-delete of the first match. */\n\tconsumeOne?: (model: string, where: Record<string, unknown>) => unknown;\n\t/** Atomic guarded add to numeric fields of the first match. */\n\tincrementOne?: (\n\t\tmodel: string,\n\t\twhere: Record<string, unknown>,\n\t\tincrements: Record<string, number>,\n\t) => unknown;\n\t/** Run `run` against a transaction-bound view of this adapter:\n\t * committed when it resolves, rolled back when it throws. */\n\ttransaction?: <T>(run: (tx: StorageAdapter) => Promise<T>) => Promise<T>;\n};\n\n/** The DUMMY adapter: rows in arrays, one per model. Implements the whole\n * surface - the optional verbs by mutation (single-threaded, so \"atomic\"),\n * transactions by snapshot-and-restore. */\nexport const memoryAdapter = (): StorageAdapter => {\n\tlet tables = new Map<string, Record<string, unknown>[]>();\n\tconst rows = (model: string) => {\n\t\tlet list = tables.get(model);\n\t\tif (!list) {\n\t\t\tlist = [];\n\t\t\ttables.set(model, list);\n\t\t}\n\t\treturn list;\n\t};\n\tconst self: StorageAdapter = {\n\t\tcreate: (model, data) => {\n\t\t\tconst row = { ...data };\n\t\t\trows(model).push(row);\n\t\t\treturn row;\n\t\t},\n\t\tfindOne: (model, where) =>\n\t\t\trows(model).find((row) => matchesWhere(row, where)) ?? null,\n\t\tfindMany: (model, where, options) => {\n\t\t\tlet list = rows(model).filter((row) => matchesWhere(row, where));\n\t\t\tconst sort = options?.sortBy;\n\t\t\tif (sort) {\n\t\t\t\tconst direction = sort.direction === \"desc\" ? -1 : 1;\n\t\t\t\tlist = [...list].sort(\n\t\t\t\t\t(a, b) => direction * compare(a[sort.field], b[sort.field]),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst start = options?.offset ?? 0;\n\t\t\tconst end =\n\t\t\t\toptions?.limit === undefined ? undefined : start + options.limit;\n\t\t\treturn start === 0 && end === undefined ? list : list.slice(start, end);\n\t\t},\n\t\tupdate: (model, where, patch) => {\n\t\t\tconst row = rows(model).find((r) => matchesWhere(r, where));\n\t\t\treturn row ? Object.assign(row, patch) : null;\n\t\t},\n\t\tdelete: (model, where) => {\n\t\t\tconst list = rows(model);\n\t\t\tconst keep = list.filter((row) => !matchesWhere(row, where));\n\t\t\ttables.set(model, keep);\n\t\t\treturn list.length - keep.length;\n\t\t},\n\t\tcount: (model, where) =>\n\t\t\trows(model).filter((row) => matchesWhere(row, where)).length,\n\t\tconsumeOne: (model, where) => {\n\t\t\tconst list = rows(model);\n\t\t\tconst index = list.findIndex((row) => matchesWhere(row, where));\n\t\t\treturn index === -1 ? null : list.splice(index, 1)[0];\n\t\t},\n\t\tincrementOne: (model, where, increments) => {\n\t\t\tconst row = rows(model).find((r) => matchesWhere(r, where));\n\t\t\tif (!row) return null;\n\t\t\tfor (const [field, by] of Object.entries(increments)) {\n\t\t\t\trow[field] = ((row[field] as number) ?? 0) + by;\n\t\t\t}\n\t\t\treturn row;\n\t\t},\n\t\ttransaction: async (run) => {\n\t\t\tconst snapshot = new Map(\n\t\t\t\t[...tables].map(([model, list]) => [\n\t\t\t\t\tmodel,\n\t\t\t\t\tlist.map((row) => ({ ...row })),\n\t\t\t\t]),\n\t\t\t);\n\t\t\ttry {\n\t\t\t\treturn await run(self);\n\t\t\t} catch (thrown) {\n\t\t\t\ttables = snapshot;\n\t\t\t\tthrow thrown;\n\t\t\t}\n\t\t},\n\t};\n\treturn self;\n};\n\n/* ---------------------------------- models ---------------------------------- */\n\ntype AnyVar = VarDefination<any, any, any, any>;\n\n/** Persistence facts about one field the ROW SHAPE can't say - consumed by\n * schema generators and adapters, never acted on by the runtime. (Read\n * shaping like redaction is a `$on` hook, not metadata.) */\nexport type FieldMeta = {\n\t/** No two rows share a value. */\n\tunique?: boolean;\n\t/** Worth an index. */\n\tindex?: boolean;\n\t/** Foreign key: this field holds `model.field` values. */\n\treferences?: {\n\t\tmodel: string;\n\t\tfield: string;\n\t\tonDelete?: \"cascade\" | \"set null\" | \"restrict\";\n\t};\n};\n\n/** What an op subscription hands back: `v.on` entries to mount. */\ntype SubscriptionEntries = OnEntry<string> | readonly OnEntry<string>[];\n\n/**\n * A model declared WITH its persistence: `schema` is the var (the shape),\n * `fields` carries per-field storage metadata, and each op key SUBSCRIBES\n * that op to app events - handed the bound collection op, it returns `v.on`\n * entries that mount wherever the storage does (`use: [db]`). An\n * already-built entry works in place of the fn.\n */\nexport type ModelConfig<SV extends AnyVar = AnyVar> = {\n\tschema: SV;\n\tfields?: {\n\t\t[F in keyof NonNullable<ValueOfVar<SV>>]?: FieldMeta;\n\t};\n} & {\n\t[Op in StorageOp]?:\n\t\t| ((\n\t\t\t\taction: Collection<NonNullable<ValueOfVar<SV>>>[Op],\n\t\t  ) => SubscriptionEntries)\n\t\t| SubscriptionEntries;\n};\n\n/** A model is a bare var, or a config carrying the var as `schema`. */\ntype ModelInput = AnyVar | ModelConfig;\n\n/** The var behind a model input. Checked through `$var`, never `schema` -\n * a bare var also HAS a `schema` property (its type shape). */\ntype SchemaOf<T> = T extends { $var: true }\n\t? T\n\t: T extends { schema: infer SV }\n\t\t? SV\n\t\t: never;\n\ntype RowOf<T> = NonNullable<ValueOfVar<SchemaOf<T>>>;\n\nexport type StorageModels = Record<string, ModelInput>;\n\nexport type StorageOp =\n\t| \"create\"\n\t| \"findOne\"\n\t| \"findMany\"\n\t| \"update\"\n\t| \"delete\"\n\t| \"count\"\n\t| \"consumeOne\"\n\t| \"incrementOne\";\n\n/** What a storage hook sees: which model and op, with the op's arguments\n * positionally (`create` -> [data], `update` -> [where, patch], `findMany`\n * -> [where, options], `incrementOne` -> [where, increments], ...). */\nexport type StorageHookContext = {\n\t/** The model KEY being addressed (the storage's property name). */\n\tmodel: string;\n\top: StorageOp;\n\targs: readonly unknown[];\n};\n\n/** `next()` runs the op (hooks below it included) and resolves its result;\n * the hook's own return value IS the op's result - wrap, veto, transform. */\nexport type StorageHook = (\n\tc: StorageHookContext,\n\tnext: () => Promise<unknown>,\n) => unknown;\n\n/** Every target a storage hook can name - a flat union, so editors offer\n * the whole surface: exact (\"user.create\"), per-model (\"user.*\"), per-op\n * (\"*.create\"), everything (\"*\"). */\nexport type StorageTarget<M> =\n\t| \"*\"\n\t| `${keyof M & string}.${StorageOp | \"*\"}`\n\t| `*.${StorageOp}`;\n\nexport type Storage<M extends StorageModels> = {\n\t[K in keyof M]: Collection<RowOf<M[K]>>;\n} & StorageApi<M>;\n\n/** The customization surface, `$`-prefixed so model keys never collide. */\nexport type StorageApi<M extends StorageModels> = {\n\t/** Swap the backend IN PLACE: every view of this storage - and every\n\t * module that captured it - starts hitting the new adapter. */\n\t$adapter: (adapter: StorageAdapter) => Storage<M>;\n\t/** Intercept ops: hooks stack in mount order and apply to every view\n\t * sharing this storage's state. */\n\t$on: (target: StorageTarget<M>, hook: StorageHook) => Storage<M>;\n\t/** A view WITHOUT these models - same adapter, same hooks. */\n\t$omit: <K extends keyof M & string>(...keys: K[]) => Storage<Omit<M, K>>;\n\t/** A view of ONLY these models - same adapter, same hooks. */\n\t$pick: <K extends keyof M & string>(...keys: K[]) => Storage<Pick<M, K>>;\n\t/** A view with MORE models - same adapter, same hooks. */\n\t$extend: <M2 extends StorageModels>(models: M2) => Storage<M & M2>;\n\t/** Run `fn` against a view whose ops share ONE adapter transaction -\n\t * committed when it resolves, rolled back when it throws. Same models,\n\t * same hooks (they run inside). An adapter without `transaction` runs\n\t * `fn` plainly - no atomicity, same answer. */\n\t$transaction: <T>(fn: (tx: Storage<M>) => Promise<T> | T) => Promise<T>;\n\t/** The model definitions this view exposes. */\n\t$models: M;\n};\n\n/** Adapter, hooks and produced subscription entries live HERE, shared by\n * every view of one storage - a `$pick`ed slice still writes through the\n * same backend and hook stack, and a subscription materializes ONCE (same\n * entry object across views, so double-mounting dedups by identity). */\ntype StorageState = {\n\tadapter: StorageAdapter;\n\thooks: { target: string; hook: StorageHook }[];\n\tsubscriptions: Map<string, readonly OnEntry<string>[]>;\n};\n\nconst OPS: readonly StorageOp[] = [\n\t\"create\",\n\t\"findOne\",\n\t\"findMany\",\n\t\"update\",\n\t\"delete\",\n\t\"count\",\n\t\"consumeOne\",\n\t\"incrementOne\",\n];\n\n/** The op against the backend, optional verbs falling back to the required\n * six: find-then-write - correct alone, racy under contention. The comment\n * every fallback deserves lives on `StorageAdapter`. */\nconst rawOp = (\n\tadapter: StorageAdapter,\n\tname: string,\n\top: StorageOp,\n\targs: unknown[],\n) => {\n\tif (op === \"consumeOne\" && !adapter.consumeOne) {\n\t\treturn (async () => {\n\t\t\tconst where = args[0] as Record<string, unknown>;\n\t\t\tconst row = (await adapter.findOne(name, where)) as Record<\n\t\t\t\tstring,\n\t\t\t\tunknown\n\t\t\t> | null;\n\t\t\tif (!row) return null;\n\t\t\t// Delete THE row by its own fields, not the where - an operator\n\t\t\t// where (`expiresAt: { lt }`) must not sweep other matches.\n\t\t\tawait adapter.delete(name, row);\n\t\t\treturn row;\n\t\t})();\n\t}\n\tif (op === \"incrementOne\" && !adapter.incrementOne) {\n\t\treturn (async () => {\n\t\t\tconst [where, increments] = args as [\n\t\t\t\tRecord<string, unknown>,\n\t\t\t\tRecord<string, number>,\n\t\t\t];\n\t\t\tconst row = (await adapter.findOne(name, where)) as Record<\n\t\t\t\tstring,\n\t\t\t\tunknown\n\t\t\t> | null;\n\t\t\tif (!row) return null;\n\t\t\tconst patch = Object.fromEntries(\n\t\t\t\tObject.entries(increments).map(([field, by]) => [\n\t\t\t\t\tfield,\n\t\t\t\t\t((row[field] as number) ?? 0) + by,\n\t\t\t\t]),\n\t\t\t);\n\t\t\treturn adapter.update(name, where, patch);\n\t\t})();\n\t}\n\treturn (adapter[op] as (...a: unknown[]) => unknown)(name, ...args);\n};\n\nconst buildStorage = <M extends StorageModels>(\n\tstate: StorageState,\n\tmodels: M,\n): Storage<M> => {\n\t// Every op funnels here: matching hooks compose around the adapter\n\t// call, first mounted outermost - the `v.on` rules, one layer down.\n\tconst run = (key: string, name: string, op: StorageOp, args: unknown[]) => {\n\t\tconst base = () => Promise.resolve(rawOp(state.adapter, name, op, args));\n\t\treturn state.hooks\n\t\t\t.filter((entry) => matchesTarget(entry.target, `${key}.${op}`))\n\t\t\t.reduceRight<() => Promise<unknown>>(\n\t\t\t\t(next, entry) => () =>\n\t\t\t\t\tPromise.resolve(entry.hook({ model: key, op, args }, next)),\n\t\t\t\tbase,\n\t\t\t)();\n\t};\n\n\tconst storage: Record<string, unknown> = {};\n\tfor (const [key, input] of Object.entries(models)) {\n\t\tconst def = isVar(input) ? input : (input as ModelConfig).schema;\n\t\tconst name = (def as { name: string }).name;\n\t\tconst collection = {\n\t\t\tcreate: (data: unknown) => run(key, name, \"create\", [data]),\n\t\t\tfindOne: (where: unknown) => run(key, name, \"findOne\", [where]),\n\t\t\tfindMany: (where?: unknown, options?: unknown) =>\n\t\t\t\trun(key, name, \"findMany\", [where, options]),\n\t\t\tupdate: (where: unknown, patch: unknown) =>\n\t\t\t\trun(key, name, \"update\", [where, patch]),\n\t\t\tdelete: (where: unknown) => run(key, name, \"delete\", [where]),\n\t\t\tcount: (where?: unknown) => run(key, name, \"count\", [where]),\n\t\t\tconsumeOne: (where: unknown) => run(key, name, \"consumeOne\", [where]),\n\t\t\tincrementOne: (where: unknown, increments: unknown) =>\n\t\t\t\trun(key, name, \"incrementOne\", [where, increments]),\n\t\t} satisfies Record<StorageOp, unknown>;\n\t\tstorage[key] = collection;\n\n\t\t// Op subscriptions become PROPERTIES of the storage, so mounting it\n\t\t// as a module (`use: [db]`) mounts the persistence it declared.\n\t\t// Materialized once per state - views share entry identity.\n\t\tif (isVar(input)) continue;\n\t\tfor (const op of OPS) {\n\t\t\tconst declared = (input as Record<string, unknown>)[op];\n\t\t\tif (!declared) continue;\n\t\t\tconst cacheKey = `${key}.${op}`;\n\t\t\tlet entries = state.subscriptions.get(cacheKey);\n\t\t\tif (!entries) {\n\t\t\t\tconst produced =\n\t\t\t\t\ttypeof declared === \"function\"\n\t\t\t\t\t\t? declared(collection[op])\n\t\t\t\t\t\t: (declared as SubscriptionEntries);\n\t\t\t\tentries = Array.isArray(produced) ? produced : [produced];\n\t\t\t\tstate.subscriptions.set(cacheKey, entries as OnEntry<string>[]);\n\t\t\t}\n\t\t\tentries.forEach((entry, index) => {\n\t\t\t\tstorage[`${key}$${op}${index === 0 ? \"\" : index}`] = entry;\n\t\t\t});\n\t\t}\n\t}\n\n\tconst self: Storage<M> = Object.assign(storage, {\n\t\t$adapter: (adapter: StorageAdapter) => {\n\t\t\tstate.adapter = adapter;\n\t\t\treturn self;\n\t\t},\n\t\t$on: (target: StorageTarget<M>, hook: StorageHook) => {\n\t\t\tstate.hooks.push({ target, hook });\n\t\t\treturn self;\n\t\t},\n\t\t$omit: (...keys: string[]) =>\n\t\t\tbuildStorage(\n\t\t\t\tstate,\n\t\t\t\tObject.fromEntries(\n\t\t\t\t\tObject.entries(models).filter(([key]) => !keys.includes(key)),\n\t\t\t\t) as StorageModels,\n\t\t\t),\n\t\t$pick: (...keys: string[]) =>\n\t\t\tbuildStorage(\n\t\t\t\tstate,\n\t\t\t\tObject.fromEntries(\n\t\t\t\t\tkeys.map((key) => [key, models[key]]),\n\t\t\t\t) as StorageModels,\n\t\t\t),\n\t\t$extend: (more: StorageModels) =>\n\t\t\tbuildStorage(state, { ...models, ...more }),\n\t\t$transaction: <T>(fn: (tx: Storage<M>) => Promise<T> | T) => {\n\t\t\t// The tx view is this storage with only the adapter swapped:\n\t\t\t// hooks and subscriptions stay the SHARED arrays, so they apply\n\t\t\t// (and mount) inside exactly as outside.\n\t\t\tconst inside = (adapter: StorageAdapter) =>\n\t\t\t\tPromise.resolve(fn(buildStorage({ ...state, adapter }, models)));\n\t\t\treturn state.adapter.transaction\n\t\t\t\t? state.adapter.transaction((tx) => inside(tx))\n\t\t\t\t: inside(state.adapter);\n\t\t},\n\t\t$models: models,\n\t} as StorageApi<M>) as Storage<M>;\n\treturn self;\n};\n\n/**\n * MANY instances of a var: each model is a collection of rows shaped like\n * the var's VALUE, addressed by the var's NAME - the var stays what it\n * always was (the scope's one current instance), the storage holds every\n * other one, and the query API is how rows move between the two.\n *\n * The returned storage is CUSTOMIZABLE through its `$` surface: `$adapter`\n * swaps the backend in place, `$on` mounts hooks around ops,\n * `$omit`/`$pick`/`$extend` derive model views over the same state, and\n * `$transaction` scopes ops to one adapter transaction.\n *\n * A model can also DECLARE its persistence: pass `{ schema, create: ... }`\n * instead of the bare var, and the op subscriptions ride on the storage as\n * mountable `v.on` entries - `use: [db]` wires them into the app. The same\n * config carries `fields` metadata (unique, index, references) for schema\n * generators to consume.\n */\nexport const makeStorage = <const M extends StorageModels>(\n\tadapter: StorageAdapter,\n\tmodels: M,\n): Storage<M> =>\n\tbuildStorage({ adapter, hooks: [], subscriptions: new Map() }, models);\n"],"mappings":";;;AA+BA,MAAM,YAAmC;CACxC,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,KAAK;CACL,IAAI;CACJ,KAAK;CACL,IAAI;CACJ,OAAO;CACP,UAAU;CACV,YAAY;CACZ,UAAU;AACX;;;AAIA,MAAM,SAAS,UACd,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,MAAM,QAAQ,KAAK,KACpB,EAAE,iBAAiB,SACnB,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,KAC5B,OAAO,KAAK,KAAK,CAAC,CAAC,OAAO,QAAQ,OAAO,SAAS;;;AAInD,MAAa,gBACZ,QAAiC,CAAC,MAElC,OAAO,QAAQ,KAAK,CAAC,CAAC,SAAS,CAAC,OAAO,UACtC,MAAM,IAAI,IACP,OAAO,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,YAAY;CAC3C;CACI;CACJ;AACD,EAAE,IACD,CAAC;CAAE;CAAO,IAAI;CAAe,OAAO;AAAK,CAAC,CAC9C;;AAGD,MAAM,YAAY,UACjB,iBAAiB,OAAO,MAAM,QAAQ,IAAI;AAE3C,MAAM,UAAU,GAAY,MAAe,SAAS,CAAC,MAAM,SAAS,CAAC;AAErE,MAAM,WAAW,GAAY,MAAuB;CACnD,MAAM,OAAO,SAAS,CAAC;CACvB,MAAM,QAAQ,SAAS,CAAC;CACxB,OAAO,OAAO,QAAQ,KAAK,OAAO,QAAQ,IAAI;AAC/C;AAEA,MAAM,SACL,KACA,EAAE,OAAO,IAAI,YACA;CACb,MAAM,UAAU,IAAI;CACpB,QAAQ,IAAR;EACC,KAAK,MACJ,OAAO,OAAO,SAAS,KAAK;EAC7B,KAAK,MACJ,OAAO,CAAC,OAAO,SAAS,KAAK;EAC9B,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,OAAO;GACX,IAAI,WAAW,QAAQ,SAAS,MAAM,OAAO;GAC7C,MAAM,QAAQ,QAAQ,SAAS,KAAK;GACpC,IAAI,OAAO,MAAM,OAAO,QAAQ;GAChC,IAAI,OAAO,OAAO,OAAO,SAAS;GAClC,IAAI,OAAO,MAAM,OAAO,QAAQ;GAChC,OAAO,SAAS;EACjB;EACA,KAAK,MACJ,OAAQ,MAA6B,MAAM,WAC1C,OAAO,SAAS,MAAM,CACvB;EACD,KAAK,SACJ,OAAO,CAAE,MAA6B,MAAM,WAC3C,OAAO,SAAS,MAAM,CACvB;EACD,KAAK,YACJ,OAAO,OAAO,YAAY,YAAY,QAAQ,SAAS,KAAe;EACvE,KAAK,cACJ,OAAO,OAAO,YAAY,YAAY,QAAQ,WAAW,KAAe;EACzE,KAAK,YACJ,OAAO,OAAO,YAAY,YAAY,QAAQ,SAAS,KAAe;CACxE;AACD;;;AAIA,MAAa,gBACZ,KACA,QAAiC,CAAC,MACrB,aAAa,KAAK,CAAC,CAAC,OAAO,cAAc,MAAM,KAAK,SAAS,CAAC;;;;AA8E5E,MAAa,sBAAsC;CAClD,IAAI,yBAAS,IAAI,IAAuC;CACxD,MAAM,QAAQ,UAAkB;EAC/B,IAAI,OAAO,OAAO,IAAI,KAAK;EAC3B,IAAI,CAAC,MAAM;GACV,OAAO,CAAC;GACR,OAAO,IAAI,OAAO,IAAI;EACvB;EACA,OAAO;CACR;CACA,MAAM,OAAuB;EAC5B,SAAS,OAAO,SAAS;GACxB,MAAM,MAAM,EAAE,GAAG,KAAK;GACtB,KAAK,KAAK,CAAC,CAAC,KAAK,GAAG;GACpB,OAAO;EACR;EACA,UAAU,OAAO,UAChB,KAAK,KAAK,CAAC,CAAC,MAAM,QAAQ,aAAa,KAAK,KAAK,CAAC,KAAK;EACxD,WAAW,OAAO,OAAO,YAAY;GACpC,IAAI,OAAO,KAAK,KAAK,CAAC,CAAC,QAAQ,QAAQ,aAAa,KAAK,KAAK,CAAC;GAC/D,MAAM,OAAO,SAAS;GACtB,IAAI,MAAM;IACT,MAAM,YAAY,KAAK,cAAc,SAAS,KAAK;IACnD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,MACf,GAAG,MAAM,YAAY,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,CAC3D;GACD;GACA,MAAM,QAAQ,SAAS,UAAU;GACjC,MAAM,MACL,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,QAAQ,QAAQ;GAC5D,OAAO,UAAU,KAAK,QAAQ,KAAA,IAAY,OAAO,KAAK,MAAM,OAAO,GAAG;EACvE;EACA,SAAS,OAAO,OAAO,UAAU;GAChC,MAAM,MAAM,KAAK,KAAK,CAAC,CAAC,MAAM,MAAM,aAAa,GAAG,KAAK,CAAC;GAC1D,OAAO,MAAM,OAAO,OAAO,KAAK,KAAK,IAAI;EAC1C;EACA,SAAS,OAAO,UAAU;GACzB,MAAM,OAAO,KAAK,KAAK;GACvB,MAAM,OAAO,KAAK,QAAQ,QAAQ,CAAC,aAAa,KAAK,KAAK,CAAC;GAC3D,OAAO,IAAI,OAAO,IAAI;GACtB,OAAO,KAAK,SAAS,KAAK;EAC3B;EACA,QAAQ,OAAO,UACd,KAAK,KAAK,CAAC,CAAC,QAAQ,QAAQ,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC;EACvD,aAAa,OAAO,UAAU;GAC7B,MAAM,OAAO,KAAK,KAAK;GACvB,MAAM,QAAQ,KAAK,WAAW,QAAQ,aAAa,KAAK,KAAK,CAAC;GAC9D,OAAO,UAAU,KAAK,OAAO,KAAK,OAAO,OAAO,CAAC,CAAC,CAAC;EACpD;EACA,eAAe,OAAO,OAAO,eAAe;GAC3C,MAAM,MAAM,KAAK,KAAK,CAAC,CAAC,MAAM,MAAM,aAAa,GAAG,KAAK,CAAC;GAC1D,IAAI,CAAC,KAAK,OAAO;GACjB,KAAK,MAAM,CAAC,OAAO,OAAO,OAAO,QAAQ,UAAU,GAClD,IAAI,UAAW,IAAI,UAAqB,KAAK;GAE9C,OAAO;EACR;EACA,aAAa,OAAO,QAAQ;GAC3B,MAAM,WAAW,IAAI,IACpB,CAAC,GAAG,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAClC,OACA,KAAK,KAAK,SAAS,EAAE,GAAG,IAAI,EAAE,CAC/B,CAAC,CACF;GACA,IAAI;IACH,OAAO,MAAM,IAAI,IAAI;GACtB,SAAS,QAAQ;IAChB,SAAS;IACT,MAAM;GACP;EACD;CACD;CACA,OAAO;AACR;AAoIA,MAAM,MAA4B;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACD;;;;AAKA,MAAM,SACL,SACA,MACA,IACA,SACI;CACJ,IAAI,OAAO,gBAAgB,CAAC,QAAQ,YACnC,QAAQ,YAAY;EACnB,MAAM,QAAQ,KAAK;EACnB,MAAM,MAAO,MAAM,QAAQ,QAAQ,MAAM,KAAK;EAI9C,IAAI,CAAC,KAAK,OAAO;EAGjB,MAAM,QAAQ,OAAO,MAAM,GAAG;EAC9B,OAAO;CACR,EAAA,CAAG;CAEJ,IAAI,OAAO,kBAAkB,CAAC,QAAQ,cACrC,QAAQ,YAAY;EACnB,MAAM,CAAC,OAAO,cAAc;EAI5B,MAAM,MAAO,MAAM,QAAQ,QAAQ,MAAM,KAAK;EAI9C,IAAI,CAAC,KAAK,OAAO;EACjB,MAAM,QAAQ,OAAO,YACpB,OAAO,QAAQ,UAAU,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAC/C,QACE,IAAI,UAAqB,KAAK,EACjC,CAAC,CACF;EACA,OAAO,QAAQ,OAAO,MAAM,OAAO,KAAK;CACzC,EAAA,CAAG;CAEJ,OAAQ,QAAQ,GAAG,CAAkC,MAAM,GAAG,IAAI;AACnE;AAEA,MAAM,gBACL,OACA,WACgB;CAGhB,MAAM,OAAO,KAAa,MAAc,IAAe,SAAoB;EAC1E,MAAM,aAAa,QAAQ,QAAQ,MAAM,MAAM,SAAS,MAAM,IAAI,IAAI,CAAC;EACvE,OAAO,MAAM,MACX,QAAQ,UAAUA,eAAAA,cAAc,MAAM,QAAQ,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAC9D,aACC,MAAM,gBACN,QAAQ,QAAQ,MAAM,KAAK;GAAE,OAAO;GAAK;GAAI;EAAK,GAAG,IAAI,CAAC,GAC3D,IACD,CAAC,CAAC;CACJ;CAEA,MAAM,UAAmC,CAAC;CAC1C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,GAAG;EAElD,MAAM,QADMC,eAAAA,MAAM,KAAK,IAAI,QAAS,MAAsB,OAAA,CACnB;EACvC,MAAM,aAAa;GAClB,SAAS,SAAkB,IAAI,KAAK,MAAM,UAAU,CAAC,IAAI,CAAC;GAC1D,UAAU,UAAmB,IAAI,KAAK,MAAM,WAAW,CAAC,KAAK,CAAC;GAC9D,WAAW,OAAiB,YAC3B,IAAI,KAAK,MAAM,YAAY,CAAC,OAAO,OAAO,CAAC;GAC5C,SAAS,OAAgB,UACxB,IAAI,KAAK,MAAM,UAAU,CAAC,OAAO,KAAK,CAAC;GACxC,SAAS,UAAmB,IAAI,KAAK,MAAM,UAAU,CAAC,KAAK,CAAC;GAC5D,QAAQ,UAAoB,IAAI,KAAK,MAAM,SAAS,CAAC,KAAK,CAAC;GAC3D,aAAa,UAAmB,IAAI,KAAK,MAAM,cAAc,CAAC,KAAK,CAAC;GACpE,eAAe,OAAgB,eAC9B,IAAI,KAAK,MAAM,gBAAgB,CAAC,OAAO,UAAU,CAAC;EACpD;EACA,QAAQ,OAAO;EAKf,IAAIA,eAAAA,MAAM,KAAK,GAAG;EAClB,KAAK,MAAM,MAAM,KAAK;GACrB,MAAM,WAAY,MAAkC;GACpD,IAAI,CAAC,UAAU;GACf,MAAM,WAAW,GAAG,IAAI,GAAG;GAC3B,IAAI,UAAU,MAAM,cAAc,IAAI,QAAQ;GAC9C,IAAI,CAAC,SAAS;IACb,MAAM,WACL,OAAO,aAAa,aACjB,SAAS,WAAW,GAAG,IACtB;IACL,UAAU,MAAM,QAAQ,QAAQ,IAAI,WAAW,CAAC,QAAQ;IACxD,MAAM,cAAc,IAAI,UAAU,OAA4B;GAC/D;GACA,QAAQ,SAAS,OAAO,UAAU;IACjC,QAAQ,GAAG,IAAI,GAAG,KAAK,UAAU,IAAI,KAAK,WAAW;GACtD,CAAC;EACF;CACD;CAEA,MAAM,OAAmB,OAAO,OAAO,SAAS;EAC/C,WAAW,YAA4B;GACtC,MAAM,UAAU;GAChB,OAAO;EACR;EACA,MAAM,QAA0B,SAAsB;GACrD,MAAM,MAAM,KAAK;IAAE;IAAQ;GAAK,CAAC;GACjC,OAAO;EACR;EACA,QAAQ,GAAG,SACV,aACC,OACA,OAAO,YACN,OAAO,QAAQ,MAAM,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,SAAS,GAAG,CAAC,CAC7D,CACD;EACD,QAAQ,GAAG,SACV,aACC,OACA,OAAO,YACN,KAAK,KAAK,QAAQ,CAAC,KAAK,OAAO,IAAI,CAAC,CACrC,CACD;EACD,UAAU,SACT,aAAa,OAAO;GAAE,GAAG;GAAQ,GAAG;EAAK,CAAC;EAC3C,eAAkB,OAA2C;GAI5D,MAAM,UAAU,YACf,QAAQ,QAAQ,GAAG,aAAa;IAAE,GAAG;IAAO;GAAQ,GAAG,MAAM,CAAC,CAAC;GAChE,OAAO,MAAM,QAAQ,cAClB,MAAM,QAAQ,aAAa,OAAO,OAAO,EAAE,CAAC,IAC5C,OAAO,MAAM,OAAO;EACxB;EACA,SAAS;CACV,CAAkB;CAClB,OAAO;AACR;;;;;;;;;;;;;;;;;;AAmBA,MAAa,eACZ,SACA,WAEA,aAAa;CAAE;CAAS,OAAO,CAAC;CAAG,+BAAe,IAAI,IAAI;AAAE,GAAG,MAAM"}

package/dist/storage.d.cts

@@ -0,0 +1,195 @@
+import { ValueOfVar, VarDefination } from "./var.cjs";
+import { OnEntry } from "./module.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. */
+type Collection<R> = {
+  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>;
+};
+/**
+ * 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.) */
+type FieldMeta = {
+  /** 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";
+  };
+};
+/** 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>>>;
+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]>>; } & StorageApi<M>;
+/** 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, makeStorage, matchesWhere, memoryAdapter };
+//# sourceMappingURL=storage.d.cts.map