@valbuild/core 0.124.0 → 0.126.0

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

@@ -1,93 +1,56 @@
-import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview, PreviewScope } from "../preview.js";
-import { FieldRender } from "../render.js";
+import { Schema } from "./index.js";
 import { SelectorSource } from "../selector/index.js";
-import { SourceObject } from "../source/index.js";
-import { ModuleFilePath, SourcePath } from "../val/index.js";
-import { SerializedLiteralSchema } from "./literal.js";
-import { SerializedObjectSchema } from "./object.js";
-import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
-export type SerializedUnionSchema = SerializedStringUnionSchema | SerializedObjectUnionSchema;
-export type SerializedStringUnionSchema = {
-    type: "union";
-    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
-    render?: FieldRender;
-    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
-    preview?: true;
-    key: SerializedLiteralSchema;
-    items: SerializedLiteralSchema[];
-    opt: boolean;
-    customValidate?: boolean;
-    readonly?: boolean;
-    hidden?: boolean;
-    description?: string;
-};
-export type SerializedObjectUnionSchema = {
-    type: "union";
-    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
-    render?: FieldRender;
-    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
-    preview?: true;
-    key: string;
-    items: SerializedObjectSchema[];
-    opt: boolean;
-    customValidate?: boolean;
-    readonly?: boolean;
-    hidden?: boolean;
-    description?: string;
-};
-type SourceOf<Key extends string | Schema<string>, T extends Schema<Key extends string ? SourceObject & {
-    [k in Key]: string;
-} : Key extends Schema<string> ? string : unknown>[]> = T extends Schema<infer S>[] ? S extends SelectorSource ? S | (Key extends Schema<infer K> ? K : never) : never : never;
-export declare class UnionSchema<Key extends string | Schema<string>, T extends Schema<Key extends string ? SourceObject & {
-    [k in Key]: string;
-} : Key extends Schema<string> ? string : unknown>[], Src extends SourceOf<Key, T> | null> extends Schema<Src> {
-    private readonly key;
-    private readonly items;
-    private readonly opt;
-    private readonly customValidateFunctions;
-    private readonly isReadonly;
-    private readonly isHidden;
-    private readonly description?;
-    private readonly renderInput;
-    private readonly previewInput;
-    describe(description: string | null): UnionSchema<Key, T, Src>;
-    validate(validationFunction: (src: Src) => false | string): UnionSchema<Key, T, Src>;
-    protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
-    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
-    nullable(): UnionSchema<Key, T, Src | null>;
-    readonly(isReadonly?: boolean): UnionSchema<Key, T, Src>;
-    hidden(isHidden?: boolean): 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;
-    /**
-     * How this field is laid out in the editor when it is the item of an array
-     * or record: `{ as: "inline" }` renders the field itself inside each row,
-     * instead of a preview row that navigates to it.
-     *
-     * Static configuration, not a callback — see `render.ts`.
-     */
-    render(input: FieldRender): UnionSchema<Key, T, Src>;
-    /**
-     * How this VALUE is shown where a preview of it is needed — a row in a
-     * sortable list, a reference dropdown, a search hit. Never how the field
-     * itself is edited (that is `render`). See `preview.ts`.
-     *
-     * Without one of its own, a tagged union previews as the VARIANT the value
-     * takes — declare `preview` on the member objects and the union dispatches.
-     */
-    preview(select: ItemPreviewInput<Src>): UnionSchema<Key, T, Src>;
-    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
-    protected declaresItemPreview(): boolean;
-    protected executeSerialize(): SerializedSchema;
-    constructor(key: Key, items: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
-    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
-}
-export declare const union: <Key extends string | Schema<string>, T extends Schema<Key extends string ? SourceObject & { [k in Key]: string; } : Key extends Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => UnionSchema<Key, T, SourceOf<Key, T>>;
+import { DiscriminatedUnionItems, DiscriminatedUnionSchema, DiscriminatedUnionSourceOf, SerializedDiscriminatedUnionSchema } from "./discriminatedUnion.js";
+import { EnumSchema, SerializedEnumSchema } from "./enum.js";
+/**
+ * @deprecated Use {@link SerializedDiscriminatedUnionSchema} or
+ * {@link SerializedEnumSchema}. A serialized union is now one or the other,
+ * distinguished by `type` rather than by the shape of `key`.
+ */
+export type SerializedUnionSchema = SerializedDiscriminatedUnionSchema | SerializedEnumSchema;
+/** @deprecated Use {@link SerializedEnumSchema}. */
+export type SerializedStringUnionSchema = SerializedEnumSchema;
+/** @deprecated Use {@link SerializedDiscriminatedUnionSchema}. */
+export type SerializedObjectUnionSchema = SerializedDiscriminatedUnionSchema;
+/**
+ * @deprecated There is no single union schema class any more: name
+ * {@link DiscriminatedUnionSchema} or {@link EnumSchema}. The type parameters
+ * are kept so existing annotations still compile, but only `Src` is used.
+ */
+export type UnionSchema<_Key = unknown, _T = unknown, Src extends SelectorSource = SelectorSource> = Schema<Src>;
+/**
+ * The value type of a list of literal schemas — how `s.union` typed a union of
+ * literals. Inferred from `Schema<infer S>` rather than `LiteralSchema<infer S>`
+ * because a `LiteralSchema` is invariant in its source (its custom validate
+ * functions put it in a parameter position), so `LiteralSchema<"a">` is not
+ * assignable to `LiteralSchema<"a" | "b">`.
+ */
+type EnumSourceOf<T extends Schema<string>[]> = T extends Schema<infer S>[] ? S extends string ? S : never : never;
+/**
+ * @deprecated Use `s.discriminatedUnion(key, ...objects)` for a tagged union of
+ * objects, or `s.enum("a", "b")` for one of a fixed set of strings.
+ *
+ * One thing does NOT survive the literal form: an enum's values are strings,
+ * so a member literal's own `.validate()` and `.describe()` are dropped rather
+ * than carried over. `s.union(s.literal("a").validate(...), ...)` ran that
+ * validator as part of deciding whether the value matched; `s.enum` has no
+ * member to run. A validator on a single-valued literal could only accept or
+ * reject that one value, which the enum's own value list already decides — but
+ * if you rely on one, keep it by validating the enum itself.
+ *
+ * @example
+ * // was: s.union("type", s.object({ type: s.literal("a"), a: s.string() }))
+ * const schema = s.discriminatedUnion(
+ *   "type",
+ *   s.object({ type: s.literal("a"), a: s.string() }),
+ * );
+ * export default c.define("/example.val.ts", schema, { type: "a", a: "one" });
+ *
+ * @example
+ * // was: s.union(s.literal("a"), s.literal("b"))
+ * const schema = s.enum("a", "b");
+ * export default c.define("/example.val.ts", schema, "a");
+ */
+export declare function union<Key extends string, T extends DiscriminatedUnionItems<Key>>(key: Key, ...objects: T): DiscriminatedUnionSchema<Key, T, DiscriminatedUnionSourceOf<Key, T>>;
+export declare function union<T extends Schema<string>[]>(...literals: T): EnumSchema<EnumSourceOf<T>>;
 export {};