@aventara/core 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/avz/avz-check.registry.js

@@ -0,0 +1,9 @@
+const checks = new WeakMap();
+export function registerAvZCheck(check, data) {
+    checks.set(check, data);
+}
+export function avzCheckOf(value) {
+    return typeof value === "object" && value !== null
+        ? checks.get(value)
+        : undefined;
+}

package/dist/avz/avz.d.ts

@@ -0,0 +1,203 @@
+import type { JsonSchemaPrimitive, JsonShape, JsonShapeValue } from "../contracts/json-shape.js";
+import { type AvZCheck } from "./avz-check.registry.js";
+/** The forms a Json Shape takes. */
+export type AvZKind = "string" | "number" | "int" | "boolean" | "null" | "literal" | "enum" | "object" | "array" | "tuple" | "record" | "union" | "discriminatedUnion" | "optional" | "nullable";
+/** The checks a shape of one kind takes: a string's, a number's, a list's length; else none. */
+type AvZShapeCheck<Kind extends AvZKind> = Kind extends "string" ? AvZCheck<"string"> : Kind extends "number" | "int" ? AvZCheck<"number"> : Kind extends "array" ? AvZCheck<"list"> : never;
+/**
+ * A Json Shape built with {@link AvZ}: opaque, its `kind` and `check` its only
+ * members. Its TypeScript type is `AvZ.infer<typeof shape>`.
+ */
+export interface AvZShape<Value = unknown, Kind extends AvZKind = AvZKind> extends JsonShape<Value> {
+    readonly kind: Kind;
+    /**
+     * The same shape with `checks` added: a string takes length, pattern and
+     * format checks, a number or an integer takes bounds and `multipleOf`, an
+     * array takes `AvZ.minItems`/`AvZ.maxItems`. No other shape takes any.
+     */
+    check(...checks: readonly AvZShapeCheck<Kind>[]): this;
+}
+/** The fields of an object shape, by key. */
+export type AvZFields = {
+    readonly [key: string]: AvZShape;
+};
+declare const avzOptionalKey: unique symbol;
+/** Marks a shape whose object key may be left out. Type-level only. */
+interface AvZOptionalKey {
+    readonly [avzOptionalKey]: true;
+}
+type FieldKeysOptional<Fields extends AvZFields> = {
+    [Key in keyof Fields]: Fields[Key] extends AvZOptionalKey ? Key : never;
+}[keyof Fields];
+type Flatten<T> = {
+    [Key in keyof T]: T[Key];
+} & {};
+/** The value an object shape describes. */
+type AvZObjectValue<Fields extends AvZFields> = ObjectValueOf<Fields, FieldKeysOptional<Fields>>;
+type ObjectValueOf<Fields extends AvZFields, Optional extends keyof Fields> = Flatten<{
+    -readonly [Key in Exclude<keyof Fields, Optional>]: JsonShapeValue<Fields[Key]>;
+} & {
+    -readonly [Key in Optional]?: JsonShapeValue<Fields[Key]>;
+}>;
+/** An object shape: closed, so a key it does not declare is refused. */
+export interface AvZObject<Fields extends AvZFields = AvZFields> extends AvZShape<AvZObjectValue<Fields>, "object"> {
+    readonly fields: Fields;
+}
+/** A shape whose object key may be left out. */
+export interface AvZOptional<Inner extends AvZShape = AvZShape> extends AvZShape<JsonShapeValue<Inner> | undefined, "optional">, AvZOptionalKey {
+}
+/** A shape that also admits `null`. */
+export type AvZNullable<Inner extends AvZShape = AvZShape> = AvZShape<JsonShapeValue<Inner> | null, "nullable"> & (Inner extends AvZOptionalKey ? AvZOptionalKey : unknown);
+/** A value a literal shape may hold. */
+type AvZLiteralValue = JsonSchemaPrimitive;
+/** What keys a record shape: any string, an enum's values or one literal. */
+type AvZRecordKey = AvZShape<string, "string"> | AvZShape<string, "enum"> | AvZShape<string, "literal">;
+/** An option of a discriminated union: an object whose discriminator is a literal or an enum. */
+type AvZDiscriminable<Discriminator extends string> = AvZObject<{
+    readonly [Key in Discriminator]: AvZShape<AvZLiteralValue, "literal"> | AvZShape<string, "enum">;
+} & AvZFields>;
+type TupleValue<Items extends readonly AvZShape[]> = {
+    -readonly [Index in keyof Items]: JsonShapeValue<Items[Index]>;
+};
+/**
+ * Builds Json Shapes (the type of a Json field, declared at
+ * `resources.<Resource>.fields.<field>.definition.json`) and checks in zod's
+ * vocabulary: a field's `validators`, and a shape node's `check(...)`. No
+ * refinements, transforms or defaults. Objects are closed: a key the shape does
+ * not declare is refused.
+ */
+export declare class AvZ {
+    private constructor();
+    /** Any string. */
+    static readonly string: () => AvZShape<string, "string">;
+    /** Any finite number. */
+    static readonly number: () => AvZShape<number, "number">;
+    /** An integer (a safe one). */
+    static readonly int: () => AvZShape<number, "int">;
+    /** `true` or `false`. */
+    static readonly boolean: () => AvZShape<boolean, "boolean">;
+    /** `null`. */
+    static readonly null: () => AvZShape<null, "null">;
+    /** Exactly `value`: a string, a finite number, a boolean or `null`. */
+    static readonly literal: <const Value extends AvZLiteralValue>(value: Value) => AvZShape<Value, "literal">;
+    /** One of `values`. */
+    static readonly enum: <const Values extends readonly [string, ...string[]]>(values: Values) => AvZShape<Values[number], "enum">;
+    /** An object with exactly these keys; `AvZ.optional` marks one that may be left out. */
+    static readonly object: <const Fields extends AvZFields>(fields: Fields) => AvZObject<Fields>;
+    /** A list of `item`s. */
+    static readonly array: <Item extends AvZShape>(item: Item) => AvZShape<JsonShapeValue<Item>[], "array">;
+    /** A list of exactly these items, in order. */
+    static readonly tuple: <const Items extends readonly [AvZShape, ...AvZShape[]]>(items: Items) => AvZShape<TupleValue<Items>, "tuple">;
+    /** An object of `value`s, keyed by any string, an enum's values or a literal. */
+    static readonly record: <Key extends AvZRecordKey, Value extends AvZShape>(key: Key, value: Value) => AvZShape<Record<JsonShapeValue<Key>, JsonShapeValue<Value>>, "record">;
+    /** Any one of `options`. */
+    static readonly union: <const Options extends readonly [AvZShape, AvZShape, ...AvZShape[]]>(options: Options) => AvZShape<JsonShapeValue<Options[number]>, "union">;
+    /** One of `options`, told apart by the literal or enum at `discriminator`. */
+    static readonly discriminatedUnion: <Discriminator extends string, const Options extends readonly [AvZDiscriminable<Discriminator>, ...AvZDiscriminable<Discriminator>[]]>(discriminator: Discriminator, options: Options) => AvZShape<JsonShapeValue<Options[number]>, "discriminatedUnion">;
+    /** An object key that may be left out. */
+    static readonly optional: <Inner extends AvZShape>(inner: Inner) => AvZOptional<Inner>;
+    /** `inner`, or `null`. */
+    static readonly nullable: <Inner extends AvZShape>(inner: Inner) => AvZNullable<Inner>;
+    /** A value below `value` (a number, a bigint or a `Date`). */
+    static readonly lt: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<Value extends Date ? "datetime" : Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A value at most `value` (a number, a bigint or a `Date`). */
+    static readonly lte: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<Value extends Date ? "datetime" : Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A value above `value` (a number, a bigint or a `Date`). */
+    static readonly gt: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<Value extends Date ? "datetime" : Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A value at least `value` (a number, a bigint or a `Date`). */
+    static readonly gte: <const Value extends number | bigint | Date>(value: Value) => AvZCheck<Value extends Date ? "datetime" : Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A value above zero. */
+    static readonly positive: () => AvZCheck<"number" | "bigint" | "decimal">;
+    /** A value at least zero. */
+    static readonly nonnegative: () => AvZCheck<"number" | "bigint" | "decimal">;
+    /** A value below zero. */
+    static readonly negative: () => AvZCheck<"number" | "bigint" | "decimal">;
+    /** A value at most zero. */
+    static readonly nonpositive: () => AvZCheck<"number" | "bigint" | "decimal">;
+    /** A multiple of `value`. */
+    static readonly multipleOf: <const Value extends number | bigint>(value: Value) => AvZCheck<Value extends bigint ? "bigint" | "decimal" : "number" | "decimal">;
+    /** A string of at most `maximum` characters; on a list field, each entry. */
+    static readonly maxLength: (maximum: number) => AvZCheck<"string">;
+    /** A string of at least `minimum` characters; on a list field, each entry. */
+    static readonly minLength: (minimum: number) => AvZCheck<"string">;
+    /** A string of exactly `length` characters; on a list field, each entry. */
+    static readonly length: (exact: number) => AvZCheck<"string">;
+    /** A list of at most `maximum` entries: a list field, or an array shape. */
+    static readonly maxItems: (maximum: number) => AvZCheck<"list">;
+    /** A list of at least `minimum` entries: a list field, or an array shape. */
+    static readonly minItems: (minimum: number) => AvZCheck<"list">;
+    /** Bytes of at most `maximum` in length. */
+    static readonly maxSize: (maximum: number) => AvZCheck<"bytes">;
+    /** Bytes of at least `minimum` in length. */
+    static readonly minSize: (minimum: number) => AvZCheck<"bytes">;
+    /** Bytes of exactly `size` in length. */
+    static readonly size: (exact: number) => AvZCheck<"bytes">;
+    /** A string the pattern matches: a JavaScript regular expression, flags included. */
+    static readonly regex: (pattern: RegExp) => AvZCheck<"string">;
+    /** A string containing `value`. */
+    static readonly includes: (value: string) => AvZCheck<"string">;
+    /** A string starting with `prefix`. */
+    static readonly startsWith: (prefix: string) => AvZCheck<"string">;
+    /** A string ending with `suffix`. */
+    static readonly endsWith: (suffix: string) => AvZCheck<"string">;
+    /** A string with no uppercase letter. */
+    static readonly lowercase: () => AvZCheck<"string">;
+    /** A string with no lowercase letter. */
+    static readonly uppercase: () => AvZCheck<"string">;
+    /** An email address. */
+    static readonly email: () => AvZCheck<"string">;
+    /** A URL. */
+    static readonly url: () => AvZCheck<"string">;
+    /** Emoji only. */
+    static readonly emoji: () => AvZCheck<"string">;
+    /** A UUID (any version). */
+    static readonly uuid: () => AvZCheck<"string">;
+    /** A GUID: any 8-4-4-4-12 hex identifier. */
+    static readonly guid: () => AvZCheck<"string">;
+    /** A Nano ID. */
+    static readonly nanoid: () => AvZCheck<"string">;
+    /** A CUID. */
+    static readonly cuid: () => AvZCheck<"string">;
+    /** A CUID2. */
+    static readonly cuid2: () => AvZCheck<"string">;
+    /** A ULID. */
+    static readonly ulid: () => AvZCheck<"string">;
+    /** An XID. */
+    static readonly xid: () => AvZCheck<"string">;
+    /** A KSUID. */
+    static readonly ksuid: () => AvZCheck<"string">;
+    /** An IPv4 address. */
+    static readonly ipv4: () => AvZCheck<"string">;
+    /** An IPv6 address. */
+    static readonly ipv6: () => AvZCheck<"string">;
+    /** An IPv4 CIDR block. */
+    static readonly cidrv4: () => AvZCheck<"string">;
+    /** An IPv6 CIDR block. */
+    static readonly cidrv6: () => AvZCheck<"string">;
+    /** Base64. */
+    static readonly base64: () => AvZCheck<"string">;
+    /** Base64url. */
+    static readonly base64url: () => AvZCheck<"string">;
+    /** A string that parses as JSON (zod's `json_string` format). */
+    static readonly jsonString: () => AvZCheck<"string">;
+    /** An E.164 phone number. */
+    static readonly e164: () => AvZCheck<"string">;
+    /** A credit card number (Luhn-checked). */
+    static readonly creditCard: () => AvZCheck<"string">;
+    /** An IBAN (checksum-checked). */
+    static readonly iban: () => AvZCheck<"string">;
+    /** A JWT. */
+    static readonly jwt: () => AvZCheck<"string">;
+    /** ISO 8601: `datetime`, `date`, `time` and `duration`. */
+    static readonly iso: Readonly<{
+        datetime: () => AvZCheck<"string">;
+        date: () => AvZCheck<"string">;
+        time: () => AvZCheck<"string">;
+        duration: () => AvZCheck<"string">;
+    }>;
+}
+export declare namespace AvZ {
+    /** The TypeScript type a shape describes. */
+    type infer<Shape extends JsonShape> = JsonShapeValue<Shape>;
+}
+export {};

package/dist/{json → avz}/avz.js

@@ -1,8 +1,26 @@
-import * as zodMini from "zod/mini";
+import { array as zodArray, boolean as zodBoolean, discriminatedUnion as zodDiscriminatedUnion, enum as zodEnum, int as zodInt, literal as zodLiteral, null as zodNull, nullable as zodNullable, number as zodNumber, optional as zodOptional, record as zodRecord, strictObject as zodStrictObject, string as zodString, tuple as zodTuple, union as zodUnion, } from "zod/mini";
+import { fieldCheckIssue, passesFieldCheck, } from "../runtime/field-check.evaluator.js";
+import * as checks from "./avz-check.factory.js";
+import { avzCheckOf, } from "./avz-check.registry.js";
 import { registerJsonShape } from "./json-shape.registry.js";
-import { translateZodIssues } from "./zod-issue.translator.js";
-const z = zodMini;
-const SHAPE_PROTOTYPE = Object.freeze(Object.create(null));
+import { AVZ_CHECK_ISSUE, translateZodIssues, } from "./zod-issue.translator.js";
+const z = {
+    string: zodString,
+    number: zodNumber,
+    int: zodInt,
+    boolean: zodBoolean,
+    null: zodNull,
+    literal: zodLiteral,
+    enum: zodEnum,
+    strictObject: zodStrictObject,
+    array: zodArray,
+    tuple: zodTuple,
+    record: zodRecord,
+    union: zodUnion,
+    discriminatedUnion: zodDiscriminatedUnion,
+    optional: zodOptional,
+    nullable: zodNullable,
+};
 const compiled = new WeakMap();
 function compiledOf(builder, value) {
     const found = typeof value === "object" && value !== null
@@ -20,10 +38,17 @@ function requiredPart(builder, value) {
     }
     return part;
 }
-function build(node, zod, schema, optionalKey = false) {
+function build(node, zod, schema, optionalKey = false, checked) {
     const shape = Object.freeze(Object.assign(Object.create(SHAPE_PROTOTYPE), { kind: node.kind }));
     const frozenSchema = deepFreeze(schema);
-    compiled.set(shape, { node, zod, schema: frozenSchema, optionalKey });
+    compiled.set(shape, {
+        node,
+        zod,
+        schema: frozenSchema,
+        optionalKey,
+        unchecked: checked?.unchecked ?? zod,
+        checks: checked?.checks ?? [],
+    });
     registerJsonShape(shape, {
         schema: frozenSchema,
         validate: (value) => {
@@ -35,6 +60,69 @@ function build(node, zod, schema, optionalKey = false) {
     });
     return shape;
 }
+const CHECKABLE = {
+    string: { target: "string", subject: "string", label: "string" },
+    number: { target: "number", subject: "number", label: "number" },
+    int: { target: "number", subject: "number", label: "int" },
+    array: { target: "list", subject: "number", label: "array" },
+};
+function shapeCheck(kind, target, added) {
+    const data = avzCheckOf(added);
+    if (data === undefined) {
+        throw new TypeError(`AvZ.${kind}(…).check: every check must be built with AvZ (AvZ.maxLength(…), AvZ.email(), …); a Zod check or any other value is not accepted.`);
+    }
+    const fits = target === "string"
+        ? data.check === "string_format" ||
+            data.check === "length_equals" ||
+            ((data.check === "max_length" || data.check === "min_length") &&
+                data.list !== true)
+        : target === "number"
+            ? (data.check === "less_than" ||
+                data.check === "greater_than" ||
+                data.check === "multiple_of") &&
+                typeof data.value === "number"
+            : (data.check === "max_length" || data.check === "min_length") &&
+                data.list === true;
+    if (!fits) {
+        throw new TypeError(`AvZ.${kind}(…).check: the check "${data.check}"${"format" in data ? ` (${data.format})` : ""} does not apply to ${kind === "array" ? "an array's length; an array takes AvZ.minItems and AvZ.maxItems" : `a${kind === "int" ? "n" : ""} ${kind} shape`}.`);
+    }
+    return data;
+}
+function zodChecks(checks, subject) {
+    return (payload) => {
+        for (const check of checks) {
+            if (passesFieldCheck(check, payload.value, subject)) {
+                continue;
+            }
+            const issue = fieldCheckIssue(check, subject, []);
+            payload.issues.push({
+                code: "custom",
+                message: issue.message,
+                input: payload.value,
+                path: [],
+                params: { [AVZ_CHECK_ISSUE]: issue },
+                continue: true,
+            });
+        }
+    };
+}
+function addChecks(...added) {
+    const part = compiledOf("check", this);
+    const kind = part.node.kind;
+    const checkable = CHECKABLE[kind];
+    if (added.length === 0) {
+        return this;
+    }
+    if (checkable === undefined) {
+        throw new TypeError(`AvZ.${kind}(…).check: only a string, number, int or array shape takes checks.`);
+    }
+    const all = [
+        ...part.checks,
+        ...added.map((check) => shapeCheck(kind, checkable.target, check)),
+    ];
+    return build(part.node, part.unchecked.check(zodChecks(all, checkable.subject)), { ...part.schema, checks: all }, part.optionalKey, { unchecked: part.unchecked, checks: all });
+}
+const SHAPE_PROTOTYPE = Object.freeze(Object.assign(Object.create(null), { check: addChecks }));
 function deepFreeze(value) {
     if (typeof value === "object" && value !== null) {
         for (const child of Object.values(value)) {
@@ -74,6 +162,10 @@ const enumShape = (values) => {
         enum: copy,
     });
 };
+function contractKeyOrder(keys) {
+    const sorted = [...keys].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+    return Object.keys(Object.fromEntries(sorted.map((key) => [key, true])));
+}
 const object = (fields) => {
     if (typeof fields !== "object" || fields === null || Array.isArray(fields)) {
         throw new TypeError("AvZ.object: the fields must be an object of shapes.");
@@ -85,12 +177,14 @@ const object = (fields) => {
     for (const key of Object.keys(fields)) {
         const part = compiledOf("object", fields[key]);
         nodes[key] = part.node;
-        zods[key] = part.zod;
         properties[key] = part.schema;
         if (!part.optionalKey) {
             required.push(key);
         }
     }
+    for (const key of contractKeyOrder(Object.keys(fields))) {
+        zods[key] = compiledOf("object", fields[key]).zod;
+    }
     return build({ kind: "object", fields: nodes }, z.strictObject(zods), {
         type: "object",
         properties,
@@ -140,7 +234,9 @@ const record = (key, value) => {
             required: [...keys],
             additionalProperties: false,
         };
-    return build({ kind: "record", value: valuePart.node }, z.record(keyPart.zod, valuePart.zod), schema);
+    return build({ kind: "record", value: valuePart.node }, z.record(keyNode.kind === "enum"
+        ? z.enum(contractKeyOrder(keyNode.values))
+        : keyPart.zod, valuePart.zod), schema);
 };
 const union = (options) => {
     if (!Array.isArray(options) || options.length < 2) {
@@ -209,4 +305,50 @@ export class AvZ {
     static discriminatedUnion = discriminatedUnion;
     static optional = optional;
     static nullable = nullable;
+    static lt = checks.lt;
+    static lte = checks.lte;
+    static gt = checks.gt;
+    static gte = checks.gte;
+    static positive = checks.positive;
+    static nonnegative = checks.nonnegative;
+    static negative = checks.negative;
+    static nonpositive = checks.nonpositive;
+    static multipleOf = checks.multipleOf;
+    static maxLength = checks.maxLength;
+    static minLength = checks.minLength;
+    static length = checks.length;
+    static maxItems = checks.maxItems;
+    static minItems = checks.minItems;
+    static maxSize = checks.maxSize;
+    static minSize = checks.minSize;
+    static size = checks.size;
+    static regex = checks.regex;
+    static includes = checks.includes;
+    static startsWith = checks.startsWith;
+    static endsWith = checks.endsWith;
+    static lowercase = checks.lowercase;
+    static uppercase = checks.uppercase;
+    static email = checks.email;
+    static url = checks.url;
+    static emoji = checks.emoji;
+    static uuid = checks.uuid;
+    static guid = checks.guid;
+    static nanoid = checks.nanoid;
+    static cuid = checks.cuid;
+    static cuid2 = checks.cuid2;
+    static ulid = checks.ulid;
+    static xid = checks.xid;
+    static ksuid = checks.ksuid;
+    static ipv4 = checks.ipv4;
+    static ipv6 = checks.ipv6;
+    static cidrv4 = checks.cidrv4;
+    static cidrv6 = checks.cidrv6;
+    static base64 = checks.base64;
+    static base64url = checks.base64url;
+    static jsonString = checks.jsonString;
+    static e164 = checks.e164;
+    static creditCard = checks.creditCard;
+    static iban = checks.iban;
+    static jwt = checks.jwt;
+    static iso = checks.iso;
 }

package/dist/{json → avz}/index.d.ts

@@ -1,6 +1,7 @@
 /**
- * `@aventara/core/json` — `AvZ`, which builds the TypeScript shape of a Json
+ * `@aventara/core/avz` — `AvZ`, which builds the TypeScript shape of a Json
  * field, and the types of the shapes it builds.
  */
+export type { ShapedJsonSchema as AvZShapedSchema } from "../contracts/json-shape.js";
 export type { AvZNullable, AvZObject, AvZOptional, AvZShape } from "./avz.js";
 export { AvZ } from "./avz.js";

package/dist/{json → avz}/json-shape.registry.d.ts

@@ -1,22 +1,23 @@
-import type { Contract } from "../contracts/contract.js";
-import type { ScalarField } from "../contracts/field.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
 import type { JsonSchema } from "../contracts/json-shape.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 /** What core may do with a Json Shape: read its Contract form, check a value. */
-export type JsonShapeRuntime = {
+type JsonShapeRuntime = {
     /** The shape's Contract form. */
     readonly schema: JsonSchema;
     /**
      * Every way `value` — a JSON value — does not conform, each at its path inside
      * the value; none when it conforms.
      */
-    readonly validate: (value: unknown) => readonly ValidationIssue[];
+    readonly validate: (value: unknown) => readonly AvValidationIssue[];
 };
-/** Records `shape` as a Json Shape. For `@aventara/core/json` only. */
+/** Records `shape` as a Json Shape. For `@aventara/core/avz` only. */
 export declare function registerJsonShape(shape: object, runtime: JsonShapeRuntime): void;
 /** The Json Shape `value` is, or `undefined` when `AvZ` did not build it. */
 export declare function jsonShapeOf(value: unknown): JsonShapeRuntime | undefined;
 /** Binds a compiled Contract field to the shape it enforces. Compiler only. */
-export declare function bindShapedField(field: ScalarField<Contract>, shape: JsonShapeRuntime): void;
+export declare function bindShapedField(field: AvScalarField<AvContract>, shape: JsonShapeRuntime): void;
 /** The shape a compiled Contract field enforces, or `undefined`. */
-export declare function shapeOfField(field: ScalarField<Contract>): JsonShapeRuntime | undefined;
+export declare function shapeOfField(field: AvScalarField<AvContract>): JsonShapeRuntime | undefined;
+export {};

package/dist/{json → avz}/zod-issue.translator.d.ts

@@ -1,5 +1,10 @@
 import type { JsonSchemaPrimitive } from "../contracts/json-shape.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+/**
+ * The key a shape node's failed check travels under in its Zod issue's `params`:
+ * the finished Aventara issue, path relative to the node (`avz.ts`).
+ */
+export declare const AVZ_CHECK_ISSUE = "aventara.check";
 /** A shape as the translator reads it: its form and its parts, no Zod. */
 export type AvZNode = {
     readonly kind: "string" | "number" | "int" | "boolean" | "null";
@@ -42,10 +47,11 @@ type ZodIssueLike = {
     readonly options?: readonly unknown[];
     readonly minimum?: unknown;
     readonly maximum?: unknown;
+    readonly params?: Readonly<Record<string, unknown>>;
 };
 /**
  * Aventara's issues for the ones Zod raised judging `value` against the shape
  * `root`: each at its path inside the value, in Zod's order.
  */
-export declare function translateZodIssues(root: AvZNode, value: unknown, issues: readonly ZodIssueLike[]): readonly ValidationIssue[];
+export declare function translateZodIssues(root: AvZNode, value: unknown, issues: readonly ZodIssueLike[]): readonly AvValidationIssue[];
 export {};

package/dist/{json → avz}/zod-issue.translator.js

@@ -1,3 +1,4 @@
+export const AVZ_CHECK_ISSUE = "aventara.check";
 const MISSING = Symbol("missing");
 function issue(code, path, message) {
     return { code, path, message };
@@ -104,6 +105,12 @@ function translateOne(root, value, zodIssue) {
         return [issue("V1000", path, "Required value missing.")];
     }
     switch (zodIssue.code) {
+        case "custom": {
+            const checked = zodIssue.params?.[AVZ_CHECK_ISSUE];
+            return checked === undefined
+                ? [issue("V1001", path, `Value does not match ${describe(node)}.`)]
+                : [{ ...checked, path: [...path, ...(checked.path ?? [])] }];
+        }
         case "invalid_type":
             return [issue("V1001", path, `Value must be ${describe(node)}.`)];
         case "invalid_value":

package/dist/compiler/contract-compiler-diagnostic.d.ts

@@ -1,5 +1,31 @@
-/** Codes of {@link ContractCompilerDiagnostic}. */
-export type ContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMPILER_UNKNOWN_FIELD" | "COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED" | "COMPILER_INCOMPLETE_FIELD" | "COMPILER_STRUCTURAL_FIELD_OVERRIDE" | "COMPILER_MISSING_SCALAR" | "COMPILER_MISSING_ENUM" | "COMPILER_DANGLING_RELATION" | "COMPILER_UNAVAILABLE_OPERATION" | "COMPILER_UNAVAILABLE_CAPABILITY" | "COMPILER_INVALID_LIFECYCLE" | "COMPILER_MISSING_READ_BEHAVIOR" | "COMPILER_INVALID_BEHAVIOR_DEPENDENCY"
+/** Codes of {@link AvContractCompilerDiagnostic}. */
+export type AvContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMPILER_UNKNOWN_FIELD" | "COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED" | "COMPILER_INCOMPLETE_FIELD" | "COMPILER_STRUCTURAL_FIELD_OVERRIDE" | "COMPILER_MISSING_SCALAR" | "COMPILER_MISSING_ENUM" | "COMPILER_DANGLING_RELATION" | "COMPILER_UNAVAILABLE_OPERATION" | "COMPILER_UNAVAILABLE_CAPABILITY" | "COMPILER_INVALID_LIFECYCLE" | "COMPILER_MISSING_READ_COMPUTE" | "COMPILER_INVALID_COMPUTE_DEPENDENCY"
+/**
+ * A Resource name the adapter model holds starts with `$`, which is reserved
+ * for the framework's own names (`ctx.$sql`, `$ref`, …).
+ */
+ | "COMPILER_RESERVED_RESOURCE_NAME"
+/**
+ * A layer exposes a unique operation variant (`find.unique`, `update.unique`,
+ * `delete.unique`, `upsert.unique`) and no complete identifier of its Resource:
+ * a Pick that did not pick one, or an Omit that hid every one.
+ */
+ | "COMPILER_MISSING_IDENTIFIER"
+/**
+ * A layer still creates a Resource (a create or upsert variant, or a nested
+ * create through a parent's relation) and leaves one of its create
+ * requirements unwritable on create: a required field hidden or with its
+ * `create` capability exempted and no `compute.create`, or a required relation
+ * not writable on create with a reference field neither writable nor computed.
+ */
+ | "COMPILER_HIDDEN_REQUIRED_FIELD"
+/**
+ * A field validator cannot apply: it is not a check built with `AvZ`, it does
+ * not fit the field's type (`AvZ.maxLength` on an `int` field, `AvZ.maxItems`
+ * on a field that is not a list), or the field is a relation or a Json field
+ * (whose checks are in its shape).
+ */
+ | "COMPILER_INVALID_VALIDATOR"
 /**
  * A field's `json` shape cannot apply: the field is not a Json field the
  * adapter discovered, the value is not a shape built with `AvZ`, or the shape
@@ -8,14 +34,14 @@ export type ContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMP
  | "COMPILER_INVALID_JSON_SHAPE"
 /**
  * The finished, hashed client projection is not a structurally valid
- * `ClientContract`. A framework-bug guard: the server never serves what its own
+ * `AvContractClient`. A framework-bug guard: the server never serves what its own
  * generator would refuse. `path` is the JSONPath inside the ClientContract
  * (`$.enums.status.values[1]`).
  */
  | "COMPILER_INVALID_CLIENT_CONTRACT";
 /** One reason a configuration could not be compiled into Contracts. */
-export type ContractCompilerDiagnostic = {
-    readonly code: ContractCompilerDiagnosticCode;
+export type AvContractCompilerDiagnostic = {
+    readonly code: AvContractCompilerDiagnosticCode;
     readonly path: string;
     readonly message: string;
 };

package/dist/compiler/contract-compiler-diagnostic.guidance.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorCodeDescription } from "../runtime/error-guidance.js";
+import type { AvContractCompilerDiagnosticCode } from "./contract-compiler-diagnostic.js";
+/** Meaning, cause and fix of every contract-compilation diagnostic code. */
+export declare const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE: {
+    readonly [C in AvContractCompilerDiagnosticCode]: ErrorCodeDescription;
+};