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

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));
+}