@valbuild/core 0.99.1 → 0.101.0

package/dist/declarations/src/schema/union.d.ts

@@ -5,7 +5,7 @@ import { SourceObject } from "../source/index.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { SerializedLiteralSchema } from "./literal.js";
 import { SerializedObjectSchema } from "./object.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedUnionSchema = SerializedStringUnionSchema | SerializedObjectUnionSchema;
 export type SerializedStringUnionSchema = {
     type: "union";
@@ -47,6 +47,14 @@ export declare class UnionSchema<Key extends string | Schema<string>, T extends
     nullable(): UnionSchema<Key, T, Src | null>;
     readonly(): UnionSchema<Key, T, Src>;
     hidden(): UnionSchema<Key, T, Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * The variant schema a value takes, for a TAGGED union (string `key`). `null`
+     * for a literal union (its variants are leaves with nothing to descend into) or
+     * when the value matches none of them — a structural error `executeValidate`
+     * already reports.
+     */
+    private matchedVariant;
     protected executeSerialize(): SerializedSchema;
     constructor(key: Key, items: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
     protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src): ReifiedRender;

package/dist/declarations/src/schema/validation/ValidationFix.d.ts

@@ -1,2 +1,2 @@
-export declare const ValidationFix: readonly ["image:add-metadata", "image:check-metadata", "image:upload-remote", "image:download-remote", "image:check-remote", "images:check-remote", "images:upload-remote", "file:add-metadata", "file:check-metadata", "file:upload-remote", "file:download-remote", "file:check-remote", "files:check-remote", "files:upload-remote", "keyof:check-keys", "router:check-route", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files"];
+export declare const ValidationFix: readonly ["image:add-metadata", "image:check-metadata", "image:upload-remote", "image:download-remote", "image:check-remote", "images:check-remote", "images:upload-remote", "file:add-metadata", "file:check-metadata", "file:upload-remote", "file:download-remote", "file:check-remote", "files:check-remote", "files:upload-remote", "keyof:check-keys", "router:check-route", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry"];
 export type ValidationFix = (typeof ValidationFix)[number];

package/dist/declarations/src/selector/index.d.ts

@@ -15,10 +15,11 @@ import { ImageSelector } from "./image.js";
 import { RichTextSelector } from "./richtext.js";
 import { ImageSource } from "../source/image.js";
 import { RemoteSource } from "../source/remote.js";
-export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends ImageSource ? ImageSelector : T extends FileSource<infer M> ? FileSelector<M> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
+import { JsonSource } from "../source/json.js";
+export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends ImageSource ? ImageSelector : T extends FileSource<infer M> ? FileSelector<M> : T extends JsonSource ? GenericSelector<JsonSource> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
 export type SelectorSource = SourcePrimitive | undefined | readonly SelectorSource[] | {
     [key: string]: SelectorSource;
-} | ImageSource | FileSource | RemoteSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
+} | ImageSource | FileSource | RemoteSource | JsonSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
 /**
  * @internal
  */

package/dist/declarations/src/source/index.d.ts

@@ -1,8 +1,9 @@
 import { FileSource } from "./file.js";
 import { ImageSource } from "./image.js";
+import { JsonSource } from "./json.js";
 import { RemoteSource } from "./remote.js";
 import { RichTextOptions, RichTextSource } from "./richtext.js";
-export type Source = SourcePrimitive | SourceObject | SourceArray | RemoteSource | FileSource | ImageSource | RichTextSource<RichTextOptions>;
+export type Source = SourcePrimitive | SourceObject | SourceArray | RemoteSource | FileSource | ImageSource | JsonSource | RichTextSource<RichTextOptions>;
 export type SourceObject = {
     [key in string]: Source;
 } & {
@@ -24,7 +25,7 @@ export type SourceObject = {
 export type SourceArray = readonly Source[];
 export type SourcePrimitive = string | number | boolean | null;
 export declare const VAL_EXTENSION: "_type";
-export declare function getValExtension(source: Source): false | "" | 0 | "remote" | "file" | null | undefined;
+export declare function getValExtension(source: Source): false | "" | 0 | "remote" | "file" | "json" | null | undefined;
 /**
  * A phantom type parameter is one that doesn't show up at runtime, but is checked statically (and only) at compile time.
  *

package/dist/declarations/src/source/json.d.ts

@@ -0,0 +1,73 @@
+import { PhantomType, Source, VAL_EXTENSION } from "./index.js";
+import { Json } from "../Json.js";
+/**
+ * The string used as the `_type` discriminator of a {@link JsonSource}.
+ */
+export declare const JSON_VAL_EXTENSION_TAG: "json";
+/**
+ * The lazy import thunk a {@link JsonSource} carries at runtime. It is NOT part
+ * of the {@link JsonSource} type because `Source` must stay JSON-serializable
+ * (it is sent over the wire as `Json`); the thunk is a runtime-only detail,
+ * read via {@link getJsonImport}.
+ */
+export type JsonImportThunk<T = unknown> = () => Promise<{
+    default: T;
+}>;
+/**
+ * A JSON source represents a record/router entry whose value is stored in a
+ * separate `*.val.json` file and loaded lazily via a dynamic `import()` thunk.
+ *
+ * This is what `c.json(() => import("./entry.val.json"))` returns.
+ *
+ * The *type* is a pure-JSON marker (`{ _type: "json", patch_id? }`) so that
+ * `Source` stays JSON-serializable. At runtime the value additionally carries a
+ * lazy import thunk (read via {@link getJsonImport}); over the wire only the
+ * marker is sent.
+ *
+ * The phantom type parameter `T` is the (loosened, see {@link JsonOf}) type of
+ * the value the JSON file resolves to. It is covariant: a `JsonSource` of a
+ * narrower value type is assignable to a `JsonSource` of a wider one.
+ */
+export type JsonSource<T = unknown> = {
+    readonly [VAL_EXTENSION]: typeof JSON_VAL_EXTENSION_TAG;
+    /** Set on uncommitted/draft entries (mirrors FileSource/RemoteSource). */
+    readonly patch_id?: string;
+} & PhantomType<T>;
+export declare function json<T = Json>(importThunk: JsonImportThunk<T>): JsonSource<T>;
+export declare function isJson(obj: unknown): obj is JsonSource;
+/**
+ * Reads the runtime-only lazy import thunk from a {@link JsonSource}. Returns
+ * `undefined` for a transport marker (sent over the wire without the thunk).
+ */
+export declare function getJsonImport(source: JsonSource): JsonImportThunk | undefined;
+/**
+ * Recursively resolves every {@link JsonSource} marker in a source tree by
+ * invoking its lazy import thunk, returning a fully-inlined source. This backs
+ * the eager `fetchVal`/`useVal` path (load everything).
+ *
+ * Markers without a runtime thunk (transport markers received over the wire)
+ * are left as-is — there is nothing to load from them locally. Other branded
+ * leaf sources (file/image/remote/richtext) are returned untouched.
+ */
+export declare function resolveJsonValues(source: Source): Promise<Source>;
+/**
+ * Loosens a (strict) schema source type `T` into the type that a
+ * `resolveJsonModule` import of the backing `*.val.json` can actually satisfy.
+ *
+ * Why this is needed: TypeScript widens literals when it infers the type of a
+ * JSON module (e.g. `"a"` becomes `string`, `1` becomes `number`, and a branded
+ * `_type: "file"` becomes `_type: string`). A strict schema type (with literal
+ * unions, `RawString` brands, etc.) would therefore reject a perfectly valid
+ * JSON file. `JsonOf<T>` performs the same widening at the type level so the
+ * JSON content typechecks against the schema as strictly as JSON allows. Runtime
+ * validation enforces the rest.
+ *
+ * The transform distributes over unions and recurses through objects/arrays,
+ * preserving structure while widening every leaf literal. Val object-unions are
+ * always discriminated, so distribute-and-recurse is sufficient (the discriminant
+ * literal widens to its base type, but the per-variant shape stays distinct and a
+ * concrete JSON value still matches exactly one variant).
+ */
+export type JsonOf<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends null ? null : T extends undefined ? undefined : T extends readonly (infer E)[] ? JsonOf<E>[] : T extends object ? {
+    [K in keyof T]: JsonOf<T[K]>;
+} : T;