@webda/content-mapper 0.0.0-stage → 4.0.0-beta.5

package/lib/schema/converter.d.ts

@@ -0,0 +1,363 @@
+import type { Checker, Project, Type } from "typescript/unstable/sync";
+import type { Node } from "typescript/unstable/ast";
+import { type JSONSchema7 } from "./types.ts";
+/**
+ * Which side of an accessor pair a schema describes.
+ *
+ * Service parameters only ever use `input`. The DTO modes exist for stage 7.2
+ * (model schemas) and are declared here so the property filter has one
+ * definition rather than two.
+ */
+export type SchemaMode = "input" | "output" | "dto-in" | "dto-out";
+/** How a `Buffer`-like type is represented. */
+export type BufferStrategy = "base64" | "binary" | "hex" | "array";
+/** Converter construction options. */
+export interface ConverterOptions {
+    /** Project the checker belongs to, needed to resolve node handles. */
+    project: Project;
+    /** The resident checker. */
+    checker: Checker;
+    /** Recursion limit; beyond it a property is left unconstrained. */
+    maxDepth?: number;
+    /** Accessor handling. */
+    mode?: SchemaMode;
+    /** Suppress the automatic `default: false` on booleans. */
+    disableBooleanDefaultToFalse?: boolean;
+    /** Representation for `Buffer` / `ArrayBuffer`. */
+    bufferStrategy?: BufferStrategy;
+}
+/**
+ * Converts TypeScript types into JSON Schema draft-07 documents.
+ *
+ * One instance may serve many conversions; `definitions` are reset per
+ * document.
+ */
+export declare class SchemaConverter {
+    private readonly project;
+    private readonly checker;
+    private readonly maxDepth;
+    private readonly mode;
+    private readonly booleanDefaultFalse;
+    private readonly bufferStrategy;
+    /** Sub-schemas hoisted out of the current document. */
+    private definitions;
+    /** Fallback resolution context when a property has no declaration. */
+    private targetNode;
+    /**
+     * @param options - project, checker and conversion settings
+     */
+    constructor(options: ConverterOptions);
+    /**
+     * Convert the type at a node into a complete schema document.
+     *
+     * Mirrors `SchemaGenerator.getSchemaFromNodes` with a single node, which is
+     * how `@webda/compiler` always calls it.
+     * @param node - a declaration or type node
+     * @returns a self-contained draft-07 document
+     */
+    fromNode(node: Node): JSONSchema7;
+    /**
+     * Convert a type into a complete schema document.
+     *
+     * Mirrors `SchemaGenerator.getSchemaFromType`.
+     * @param type - the type to convert
+     * @param contextNode - resolution context for properties without declarations
+     * @returns a self-contained draft-07 document
+     */
+    fromType(type: Type, contextNode?: Node): JSONSchema7;
+    /**
+     * Build one document: convert, hoist, inline the root, sort.
+     * @param type - the type to convert
+     * @param typeName - key the root definition is registered under
+     * @param node - resolution context
+     * @returns the finished document
+     */
+    private document;
+    /**
+     * Follow the root `$ref` into the document body.
+     *
+     * A definition can itself be a bare `$ref` — an anonymous object registered
+     * under a union-branch path, for instance — so the chain is followed to the
+     * end and every consumed definition removed.
+     * @param result - the document to flatten, mutated in place
+     */
+    private inlineRootRef;
+    /**
+     * Convert one type into `definition`, in place.
+     *
+     * The branch order matters and is taken from `@webda/schema`: literals
+     * before their widened forms, `Date` and `RegExp` before the generic
+     * class/interface handling, arrays after unions. The final `else` throws.
+     * @param type - the type to convert
+     * @param definition - schema to populate
+     * @param path - schema path, used for definition keys and error messages
+     * @param node - declaration the type came from, when there is one
+     * @param depth - recursion depth
+     * @returns whether the parent should keep the property, and its optionality
+     */
+    private property;
+    /**
+     * Merge annotations from a type alias tagged `@schemaInherits`.
+     *
+     * `type Email = string` with `@format email` on the alias only reaches the
+     * property when the alias opts in, otherwise every use of a documented alias
+     * would inherit its prose.
+     * @param definition - schema to enrich
+     * @param node - the property declaration
+     */
+    private inheritAliasDocs;
+    /**
+     * Convert a class, interface, anonymous object or generic reference.
+     *
+     * The shape is registered in `definitions` and the caller's slot replaced
+     * with a `$ref`, except at the document root where an anonymous object is
+     * inlined instead — otherwise the root would sit behind a definition keyed
+     * by its own stringified shape.
+     * @param type - the object-like type
+     * @param definition - schema slot to populate
+     * @param path - schema path
+     * @param typeName - stringified type, used as the definition key
+     * @param node - declaration context
+     * @param depth - recursion depth
+     * @returns keep or skip
+     */
+    private objectLike;
+    /**
+     * Prefer the apparent type when a type alias hides the concrete shape.
+     * @param type - the declared type
+     * @returns the type whose properties should be enumerated
+     */
+    private structuralType;
+    /**
+     * Build the `type` / `properties` / `required` / `additionalProperties`
+     * portion of an object schema.
+     *
+     * Properties are read off the **type**, not the declaration's own members,
+     * so inherited attributes are included.
+     * @param type - the object type
+     * @param path - schema path of the object
+     * @returns the object schema
+     */
+    private objectShape;
+    /**
+     * The type a property contributes to this schema, honouring accessors.
+     *
+     * For an input schema a getter-only property cannot be supplied at all; when
+     * a setter exists its parameter type is the accepted one, which is what
+     * makes the asymmetric accessors the content mapper generates meaningful.
+     * @param prop - the property symbol
+     * @param declaration - its primary declaration
+     * @param location - resolution context
+     * @returns the type to convert, or undefined to drop the property
+     */
+    private readableType;
+    /**
+     * Register a schema under a definition key and rewrite the slot as a `$ref`.
+     *
+     * Inline object types stringify to their whole shape, which makes a useless
+     * key, so those fall back to the schema path.
+     * @param rawKey - stringified type
+     * @param source - the schema to store
+     * @param slot - the caller's schema object, emptied and replaced by a `$ref`
+     * @param path - schema path, used when the key is unusable
+     */
+    private registerDefinition;
+    /**
+     * The return type of the first of `methodNames` the type declares.
+     *
+     * The apparent type is consulted first so a generic instantiation carries
+     * its type arguments into the signature.
+     * @param type - the type to inspect
+     * @param methodNames - names to try, in order
+     * @param location - resolution context
+     * @returns the return type, or undefined when no method matches
+     */
+    private methodReturnType;
+    /**
+     * Whether a type still contains an unsubstituted type parameter.
+     * @param type - the type to inspect
+     * @param seen - types already visited, guarding cycles
+     * @returns true when a type parameter is reachable
+     */
+    private mentionsTypeParameter;
+    /**
+     * The value a class accepts through `fromDto`, for the Input schema.
+     *
+     * Static and instance declarations both count, because `fromDto` is
+     * normally static. A first parameter of `never` is the explicit way to say
+     * "this attribute is never supplied".
+     * @param type - the type to inspect
+     * @param location - resolution context
+     * @returns the accepted type, `"skip"`, or undefined when absent
+     */
+    private resolveFromDto;
+    /**
+     * Whether a class is tagged `@readOnly`, opting its attributes out of Input.
+     * @param type - the type to inspect
+     * @returns true when the tag is present
+     */
+    private hasReadOnlyTag;
+    /**
+     * Reduce an intersection to the constituent that carries the data.
+     *
+     * `string & { __brand: x }` is a string, and `T & { toString(): string }`
+     * is `T` — an `allOf` of the parts would be technically true and useless.
+     * @param type - the type to simplify
+     * @returns the simplified type, or the original
+     */
+    private simplifyIntersection;
+    /**
+     * Union constituents in the order `webda.module.json` records them.
+     *
+     * `UnionType.getTypes()` returns them alphabetically, so without this every
+     * `enum` and every `type: [..]` in the corpus is reordered.
+     *
+     * TypeScript 6 exposed a union's constituents sorted by type id, and ids
+     * are issued as types are created. That has two regimes, and reproducing
+     * both is what makes this correct rather than lucky:
+     *
+     * - **Primitives** are interned when the checker starts, in a fixed order,
+     *   so they always sort ahead of everything else and among themselves by
+     *   that order. `number | string` is recorded as `["string", "number"]`.
+     * - **Literals** are interned on first use, so their ids follow the source.
+     *
+     * Sorting on 7.1's ids reproduces neither reliably: they are assigned as
+     * the session happens to query, so `"SUCCESS" | "ERROR"` came back reversed
+     * whenever something earlier in the batch had already interned `"ERROR"` —
+     * the score depended on which requests shared a worker. Primitives are
+     * ranked from the table instead, and literals from the syntax.
+     * @param type - the union type
+     * @param node - the declaration the union was reached through
+     * @returns the constituents, in the recorded order
+     */
+    private unionOrder;
+    /**
+     * Type ids of a union's constituents, in the order the syntax lists them.
+     * @param type - the union type
+     * @param node - the declaration the union was reached through
+     * @returns the ids, or undefined when there is no syntax to read
+     */
+    private declaredUnionOrder;
+    /**
+     * The `UnionTypeNode` a union type was written as, if there is one.
+     * @param type - the union type
+     * @param node - the declaration the union was reached through
+     * @returns the syntax node
+     */
+    private unionTypeNode;
+    /**
+     * Convert a union into `anyOf`, then simplify.
+     *
+     * The simplifications are what turn most unions in the corpus into the
+     * `enum` and `type: [..]` forms that appear in `webda.module.json`, so they
+     * are part of the output contract rather than cosmetic.
+     * @param type - the union type
+     * @param definition - schema to populate
+     * @param path - schema path
+     * @param node - the declaration the union was reached through
+     * @param depth - recursion depth
+     * @returns keep, and whether `undefined` was a member
+     */
+    private union;
+    /**
+     * Collapse an `anyOf` into the narrowest equivalent form.
+     * @param definition - schema carrying `anyOf`, mutated in place
+     */
+    private simplifyUnion;
+    /**
+     * Convert an intersection by merging object constituents.
+     *
+     * A merge is only sound when every constituent is an object; anything else
+     * falls back to `allOf`, which states the constraint without pretending to
+     * flatten it.
+     * @param type - the intersection type
+     * @param definition - schema to populate
+     * @param path - schema path
+     * @param depth - recursion depth
+     * @returns keep
+     */
+    private intersection;
+    /**
+     * Convert an array or tuple type.
+     * @param type - the array-like type
+     * @param definition - schema to populate
+     * @param path - schema path
+     * @param depth - recursion depth
+     * @returns keep
+     */
+    private array;
+    /**
+     * Convert a tuple into positional or homogeneous `items`.
+     * @param type - the tuple reference
+     * @param definition - schema to populate
+     * @param path - schema path
+     * @param depth - recursion depth
+     * @returns keep
+     */
+    private tuple;
+    /**
+     * Whether the type should be represented as a JSON array.
+     *
+     * Mapped types are excluded explicitly: the checker synthesises a numeric
+     * index signature for some of them, which would otherwise read as an array.
+     * @param type - the type to test
+     * @returns true when array-like
+     */
+    private isArrayLike;
+    /**
+     * The element type of an array-like type.
+     * @param type - the array-like type
+     * @returns the element type, or undefined when it cannot be resolved
+     */
+    private elementType;
+    /**
+     * Whether the type is a binary buffer.
+     * @param type - the type to test
+     * @param typeName - its stringified form
+     * @returns true for `Buffer`, `ArrayBuffer` or a `Buffer`-flavoured `Uint8Array`
+     */
+    private isBuffer;
+    /**
+     * Write the configured buffer representation.
+     * @param definition - schema to populate
+     */
+    private applyBuffer;
+    /**
+     * Whether the current mode describes values being supplied.
+     * @returns true for `input` and `dto-in`
+     */
+    private isInputMode;
+    /**
+     * Resolve a symbol's primary declaration node.
+     *
+     * `Symbol.declarations` are handles, not nodes; reaching the AST needs an
+     * explicit `resolve` against the project.
+     * @param symbol - the symbol
+     * @returns the declaration, when it has one
+     */
+    private declarationOf;
+    /**
+     * Whether a property is keyed by an ES symbol.
+     *
+     * Symbol-keyed slots are how Webda stores model internals
+     * (`[WEBDA_STORAGE]`, `[WEBDA_EVENTS]`), and none of them are JSON.
+     * @param prop - the property symbol
+     * @param declaration - its declaration
+     * @returns true when the key is an ES symbol
+     */
+    private isSymbolKeyed;
+    /**
+     * The initializer expression governing a type, if any.
+     * @param type - the type
+     * @param node - the declaration it was read from
+     * @returns the initializer expression
+     */
+    private initializerFor;
+    /**
+     * The name under which a declaration's schema is registered.
+     * @param node - the node being converted
+     * @returns the declared name, or undefined for type nodes
+     */
+    private declaredName;
+}
+//# sourceMappingURL=converter.d.ts.map

package/lib/schema/converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"converter.d.ts","sourceRoot":"","sources":["../../src/schema/converter.ts"],"names":[],"mappings":"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"}