@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.0

package/dist/json/avz.d.ts

@@ -0,0 +1,96 @@
+import type { JsonSchemaPrimitive, JsonShape, JsonShapeValue } from "../contracts/json-shape.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";
+/**
+ * A Json Shape built with {@link AvZ}: opaque, its `kind` the only member. Its
+ * TypeScript type is `AvZ.infer<typeof shape>`.
+ */
+export interface AvZShape<Value = unknown, Kind extends AvZKind = AvZKind> extends JsonShape<Value> {
+    readonly kind: Kind;
+}
+/** 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. */
+export 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 in the configuration as
+ * `fields: { Post: { meta: { json: AvZ.object({ … }) } } }`. Types only — no
+ * rules, 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>;
+}
+export declare namespace AvZ {
+    /** The TypeScript type a shape describes. */
+    type infer<Shape extends JsonShape> = JsonShapeValue<Shape>;
+}
+export {};

package/dist/json/avz.js

@@ -0,0 +1,212 @@
+import * as zodMini from "zod/mini";
+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));
+const compiled = new WeakMap();
+function compiledOf(builder, value) {
+    const found = typeof value === "object" && value !== null
+        ? compiled.get(value)
+        : undefined;
+    if (found === undefined) {
+        throw new TypeError(`AvZ.${builder}: every part of a shape must be built with AvZ (a Zod schema or any other value is not accepted).`);
+    }
+    return found;
+}
+function requiredPart(builder, value) {
+    const part = compiledOf(builder, value);
+    if (part.optionalKey) {
+        throw new TypeError(`AvZ.${builder}: AvZ.optional marks an object key that may be left out; use it only for a field of AvZ.object.`);
+    }
+    return part;
+}
+function build(node, zod, schema, optionalKey = false) {
+    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 });
+    registerJsonShape(shape, {
+        schema: frozenSchema,
+        validate: (value) => {
+            const result = zod.safeParse(value);
+            return result.success
+                ? []
+                : translateZodIssues(node, value, result.error.issues);
+        },
+    });
+    return shape;
+}
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null) {
+        for (const child of Object.values(value)) {
+            deepFreeze(child);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+function isLiteralValue(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)));
+}
+const string = () => build({ kind: "string" }, z.string(), { type: "string" });
+const number = () => build({ kind: "number" }, z.number(), { type: "number" });
+const int = () => build({ kind: "int" }, z.int(), { type: "integer" });
+const boolean = () => build({ kind: "boolean" }, z.boolean(), { type: "boolean" });
+const nullShape = () => build({ kind: "null" }, z.null(), { type: "null" });
+const literal = (value) => {
+    if (!isLiteralValue(value)) {
+        throw new TypeError("AvZ.literal: the value must be a string, a finite number, a boolean or null.");
+    }
+    return build({ kind: "literal", value }, z.literal(value), { const: value });
+};
+const enumShape = (values) => {
+    if (!Array.isArray(values) ||
+        values.length === 0 ||
+        values.some((value) => typeof value !== "string") ||
+        new Set(values).size !== values.length) {
+        throw new TypeError("AvZ.enum: the values must be a non-empty list of distinct strings.");
+    }
+    const copy = [...values];
+    return build({ kind: "enum", values: copy }, z.enum(copy), {
+        type: "string",
+        enum: copy,
+    });
+};
+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.");
+    }
+    const nodes = {};
+    const zods = {};
+    const properties = {};
+    const required = [];
+    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);
+        }
+    }
+    return build({ kind: "object", fields: nodes }, z.strictObject(zods), {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        additionalProperties: false,
+    });
+};
+const array = (item) => {
+    const part = requiredPart("array", item);
+    return build({ kind: "array", item: part.node }, z.array(part.zod), {
+        type: "array",
+        items: part.schema,
+    });
+};
+const tuple = (items) => {
+    if (!Array.isArray(items) || items.length === 0) {
+        throw new TypeError("AvZ.tuple: the items must be a non-empty list of shapes.");
+    }
+    const parts = items.map((item) => requiredPart("tuple", item));
+    return build({ kind: "tuple", items: parts.map((part) => part.node) }, z.tuple(parts.map((part) => part.zod)), {
+        type: "array",
+        prefixItems: parts.map((part) => part.schema),
+        items: false,
+        minItems: parts.length,
+        maxItems: parts.length,
+    });
+};
+const record = (key, value) => {
+    const keyPart = requiredPart("record", key);
+    const valuePart = requiredPart("record", value);
+    const keyNode = keyPart.node;
+    const keys = keyNode.kind === "enum"
+        ? keyNode.values
+        : keyNode.kind === "literal" && typeof keyNode.value === "string"
+            ? [keyNode.value]
+            : keyNode.kind === "string"
+                ? undefined
+                : null;
+    if (keys === null) {
+        throw new TypeError("AvZ.record: the key must be AvZ.string(), AvZ.enum([...]) or a string AvZ.literal(...).");
+    }
+    const schema = keys === undefined
+        ? { type: "object", additionalProperties: valuePart.schema }
+        : {
+            type: "object",
+            properties: Object.fromEntries(keys.map((entry) => [entry, valuePart.schema])),
+            required: [...keys],
+            additionalProperties: false,
+        };
+    return build({ kind: "record", value: valuePart.node }, z.record(keyPart.zod, valuePart.zod), schema);
+};
+const union = (options) => {
+    if (!Array.isArray(options) || options.length < 2) {
+        throw new TypeError("AvZ.union: the options must be a list of at least two shapes.");
+    }
+    const parts = options.map((option) => requiredPart("union", option));
+    return build({ kind: "union", options: parts.map((part) => part.node) }, z.union(parts.map((part) => part.zod)), {
+        anyOf: parts.map((part) => part.schema),
+    });
+};
+const discriminatedUnion = (discriminator, options) => {
+    if (typeof discriminator !== "string" ||
+        !Array.isArray(options) ||
+        options.length === 0) {
+        throw new TypeError("AvZ.discriminatedUnion: give the discriminator key and a non-empty list of object shapes.");
+    }
+    const parts = options.map((option) => requiredPart("discriminatedUnion", option));
+    const tags = new Map();
+    parts.forEach((part, index) => {
+        const tag = part.node.kind === "object" ? part.node.fields[discriminator] : undefined;
+        const values = tag?.kind === "literal"
+            ? [tag.value]
+            : tag?.kind === "enum"
+                ? tag.values
+                : undefined;
+        if (values === undefined) {
+            throw new TypeError(`AvZ.discriminatedUnion: option ${index} must be an AvZ.object whose "${discriminator}" is an AvZ.literal or an AvZ.enum.`);
+        }
+        for (const value of values) {
+            if (tags.has(value)) {
+                throw new TypeError(`AvZ.discriminatedUnion: options ${tags.get(value)} and ${index} both match "${discriminator}" ${JSON.stringify(value)}.`);
+            }
+            tags.set(value, index);
+        }
+    });
+    return build({
+        kind: "discriminatedUnion",
+        discriminator,
+        options: parts.map((part) => part.node),
+    }, z.discriminatedUnion(discriminator, parts.map((part) => part.zod)), {
+        oneOf: parts.map((part) => part.schema),
+    });
+};
+const optional = (inner) => {
+    const part = compiledOf("optional", inner);
+    return build({ kind: "optional", inner: part.node }, z.optional(part.zod), part.schema, true);
+};
+const nullable = (inner) => {
+    const part = compiledOf("nullable", inner);
+    return build({ kind: "nullable", inner: part.node }, z.nullable(part.zod), { anyOf: [part.schema, { type: "null" }] }, part.optionalKey);
+};
+export class AvZ {
+    constructor() { }
+    static string = string;
+    static number = number;
+    static int = int;
+    static boolean = boolean;
+    static null = nullShape;
+    static literal = literal;
+    static enum = enumShape;
+    static object = object;
+    static array = array;
+    static tuple = tuple;
+    static record = record;
+    static union = union;
+    static discriminatedUnion = discriminatedUnion;
+    static optional = optional;
+    static nullable = nullable;
+}

package/dist/json/index.d.ts

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

package/dist/json/index.js

@@ -0,0 +1 @@
+export { AvZ } from "./avz.js";

package/dist/json/json-shape.registry.d.ts

@@ -0,0 +1,22 @@
+import type { Contract } from "../contracts/contract.js";
+import type { ScalarField } from "../contracts/field.js";
+import type { JsonSchema } from "../contracts/json-shape.js";
+import type { ValidationIssue } from "../operations/validation-code.js";
+/** What core may do with a Json Shape: read its Contract form, check a value. */
+export 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[];
+};
+/** Records `shape` as a Json Shape. For `@aventara/core/json` 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;
+/** The shape a compiled Contract field enforces, or `undefined`. */
+export declare function shapeOfField(field: ScalarField<Contract>): JsonShapeRuntime | undefined;

package/dist/json/json-shape.registry.js

@@ -0,0 +1,16 @@
+const shapes = new WeakMap();
+const fields = new WeakMap();
+export function registerJsonShape(shape, runtime) {
+    shapes.set(shape, runtime);
+}
+export function jsonShapeOf(value) {
+    return typeof value === "object" && value !== null
+        ? shapes.get(value)
+        : undefined;
+}
+export function bindShapedField(field, shape) {
+    fields.set(field, shape);
+}
+export function shapeOfField(field) {
+    return fields.get(field);
+}

package/dist/json/zod-issue.translator.d.ts

@@ -0,0 +1,51 @@
+import type { JsonSchemaPrimitive } from "../contracts/json-shape.js";
+import type { ValidationIssue } from "../operations/validation-code.js";
+/** A shape as the translator reads it: its form and its parts, no Zod. */
+export type AvZNode = {
+    readonly kind: "string" | "number" | "int" | "boolean" | "null";
+} | {
+    readonly kind: "literal";
+    readonly value: JsonSchemaPrimitive;
+} | {
+    readonly kind: "enum";
+    readonly values: readonly string[];
+} | {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, AvZNode>>;
+} | {
+    readonly kind: "array";
+    readonly item: AvZNode;
+} | {
+    readonly kind: "tuple";
+    readonly items: readonly AvZNode[];
+} | {
+    readonly kind: "record";
+    readonly value: AvZNode;
+} | {
+    readonly kind: "union";
+    readonly options: readonly AvZNode[];
+} | {
+    readonly kind: "discriminatedUnion";
+    readonly discriminator: string;
+    readonly options: readonly AvZNode[];
+} | {
+    readonly kind: "optional" | "nullable";
+    readonly inner: AvZNode;
+};
+/** The members of a Zod issue this module reads. */
+type ZodIssueLike = {
+    readonly code: string;
+    readonly path: readonly PropertyKey[];
+    readonly origin?: string;
+    readonly keys?: readonly string[];
+    readonly note?: string;
+    readonly options?: readonly unknown[];
+    readonly minimum?: unknown;
+    readonly maximum?: 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 {};

package/dist/json/zod-issue.translator.js

@@ -0,0 +1,142 @@
+const MISSING = Symbol("missing");
+function issue(code, path, message) {
+    return { code, path, message };
+}
+function valueAt(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (typeof current !== "object" ||
+            current === null ||
+            !Object.hasOwn(current, segment)) {
+            return MISSING;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function unwrap(node) {
+    return node.kind === "optional" || node.kind === "nullable"
+        ? unwrap(node.inner)
+        : node;
+}
+function selectedOption(node, value) {
+    const tag = valueAt(value, [node.discriminator]);
+    return node.options.find((option) => {
+        const field = option.kind === "object" ? option.fields[node.discriminator] : undefined;
+        const inner = field === undefined ? undefined : unwrap(field);
+        return inner?.kind === "literal"
+            ? Object.is(inner.value, tag)
+            : inner?.kind === "enum" && inner.values.includes(tag);
+    });
+}
+function nodeAt(root, value, path) {
+    let node = root;
+    let current = value;
+    for (const segment of path) {
+        node = node === undefined ? undefined : unwrap(node);
+        if (node?.kind === "discriminatedUnion") {
+            node = selectedOption(node, current);
+        }
+        switch (node?.kind) {
+            case "object":
+                node = node.fields[segment];
+                break;
+            case "array":
+                node = node.item;
+                break;
+            case "tuple":
+                node = typeof segment === "number" ? node.items[segment] : undefined;
+                break;
+            case "record":
+                node = node.value;
+                break;
+            default:
+                return undefined;
+        }
+        current = valueAt(current, [segment]);
+    }
+    return node;
+}
+function describe(node) {
+    if (node === undefined) {
+        return "the field's shape";
+    }
+    switch (node.kind) {
+        case "string":
+            return "a string";
+        case "number":
+            return "a number";
+        case "int":
+            return "an integer";
+        case "boolean":
+            return "a boolean";
+        case "null":
+            return "null";
+        case "literal":
+            return JSON.stringify(node.value);
+        case "enum":
+            return `one of ${node.values.map((value) => JSON.stringify(value)).join(", ")}`;
+        case "object":
+        case "record":
+            return "an object";
+        case "array":
+            return "a list";
+        case "tuple":
+            return `a list of exactly ${node.items.length} entries`;
+        case "union":
+        case "discriminatedUnion":
+            return [...new Set(node.options.map(describe))].join(" or ");
+        case "optional":
+            return describe(node.inner);
+        case "nullable":
+            return `${describe(node.inner)} or null`;
+    }
+}
+function pathOf(path) {
+    return path.map((segment) => typeof segment === "symbol" ? String(segment) : segment);
+}
+function translateOne(root, value, zodIssue) {
+    const path = pathOf(zodIssue.path);
+    const node = nodeAt(root, value, path);
+    const absent = path.length > 0 && valueAt(value, path) === MISSING;
+    if (absent &&
+        (zodIssue.code === "invalid_type" || zodIssue.code === "invalid_value")) {
+        return [issue("V1000", path, "Required value missing.")];
+    }
+    switch (zodIssue.code) {
+        case "invalid_type":
+            return [issue("V1001", path, `Value must be ${describe(node)}.`)];
+        case "invalid_value":
+            return [issue("V1002", path, `Value must be ${describe(node)}.`)];
+        case "unrecognized_keys":
+            return (zodIssue.keys ?? []).map((key) => issue("V1005", [...path, key], "Key is not part of the shape."));
+        case "invalid_union": {
+            if (zodIssue.note !== undefined && Array.isArray(zodIssue.options)) {
+                if (absent) {
+                    return [issue("V1000", path, "Required value missing.")];
+                }
+                const allowed = zodIssue.options
+                    .map((option) => JSON.stringify(option))
+                    .join(", ");
+                return [issue("V1002", path, `Value must be one of ${allowed}.`)];
+            }
+            return [issue("V1001", path, `Value must be ${describe(node)}.`)];
+        }
+        case "too_big":
+        case "too_small":
+            if (zodIssue.origin === "array" && node !== undefined) {
+                return [issue("V1001", path, `Value must be ${describe(node)}.`)];
+            }
+            if (zodIssue.origin === "int" || zodIssue.origin === "number") {
+                return [
+                    issue("V1004", path, "Value must be a safe integer (between -9007199254740991 and 9007199254740991)."),
+                ];
+            }
+            return [issue("V1001", path, `Value does not match ${describe(node)}.`)];
+        default:
+            return [issue("V1001", path, `Value does not match ${describe(node)}.`)];
+    }
+}
+export function translateZodIssues(root, value, issues) {
+    return issues.flatMap((zodIssue) => translateOne(root, value, zodIssue));
+}