@versionzero/schema 1.0.0

package/types/traversal/executors/normalize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Normalize the assigned input value
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function normalize(state: TraversalState): TraversalState | null | undefined | Promise<TraversalState | null | undefined>;
+import { TraversalState } from '../traversal-state.js';

package/types/traversal/executors/prepare-existing.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|undefined}
+ */
+export function prepareExisting(state: TraversalState): TraversalState | undefined;
+import { TraversalState } from '../traversal-state.js';

package/types/traversal/executors/prepare-pending.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|undefined|null|Promise<TraversalState|undefined|null>}
+ */
+export function preparePending(state: TraversalState): TraversalState | undefined | null | Promise<TraversalState | undefined | null>;
+import { TraversalState } from '../traversal-state.js';

package/types/traversal/executors/resolve-union.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function resolveUnion(state: TraversalState): TraversalState | null | undefined | Promise<TraversalState | null | undefined>;
+import { TraversalState } from '../traversal-state.js';

package/types/traversal/executors/serialize.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Serialize the pending/input and save as output state value
+ *
+ * Runs pre-child-traversal; acts in the same way that normalize does.
+ * Setting the input will propagate down to assigned values in the child states.
+ *
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function serialize(state: TraversalState): TraversalState | null | undefined | Promise<TraversalState | null | undefined>;
+import { TraversalState } from '../traversal-state.js';

package/types/traversal/executors/transform-early.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function transformEarly(state: TraversalState): TraversalState | null | undefined | Promise<TraversalState | null | undefined>;
+import { TraversalState } from '../traversal-state.js';

package/types/traversal/executors/transform.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function transform(state: TraversalState): TraversalState | null | undefined | Promise<TraversalState | null | undefined>;
+import { TraversalState } from '../traversal-state.js';

package/types/traversal/executors/traversal-state-executor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @augments Executor<TraversalState>
+ */
+export class TraversalStateExecutor extends Executor<TraversalState> {
+    /**
+     * @param {any} enter
+     * @param {any} exit
+     */
+    constructor(enter: any, exit: any);
+    /**
+     *
+     * @param {TraversalState} state
+     * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+     */
+    execute(state: TraversalState): TraversalState | null | undefined | Promise<TraversalState | null | undefined>;
+    #private;
+}
+import { TraversalState } from '../traversal-state.js';
+import { Executor } from '../../executor/executor.js';

package/types/traversal/executors/validate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|Promise<TraversalState>}
+ */
+export function validate(state: TraversalState): TraversalState | Promise<TraversalState>;
+import { TraversalState } from '../traversal-state.js';

package/types/traversal/traversal-context.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @typedef {object} TraversalContextStandardOptions
+ * @property {boolean} [strict]
+ * @property {boolean} [deep]
+ * @property {boolean} [debug]
+ */
+/** @typedef {TraversalContextStandardOptions & {[key:string]:any}} TraversalContextOptions */
+export class TraversalContext {
+    /**
+     * @param {SchemaLocation|CompiledSchema} root
+     * @param {TraversalContextOptions} [options]
+     */
+    constructor(root: SchemaLocation | CompiledSchema, options?: TraversalContextOptions);
+    root: SchemaLocation;
+    _final: boolean;
+    _options: {
+        deep: boolean;
+        strict: boolean;
+        debug: boolean;
+    };
+    traversals: number;
+    counter: number;
+    /** @type {Map.<string,TraversalState>} */
+    stateMap: Map<string, TraversalState>;
+    _debugEnabled: boolean;
+    compiling: boolean;
+    get options(): {
+        deep: boolean;
+        strict: boolean;
+        debug: boolean;
+    };
+    get deep(): boolean;
+    get strict(): boolean;
+    update(): void;
+    set final(finalize: boolean);
+    get final(): boolean;
+    _finalizeCount: number;
+    finalize(): this;
+    get isComplete(): boolean;
+    get incomplete(): Set<any>;
+    setValue(value: any): void;
+    _value: any;
+    getValue(): any;
+    /**
+     * @param {any} input
+     * @param {string} [path]
+     */
+    setAssignedInput(input: any, path?: string): void;
+    /**
+     * @param {string|SchemaLocation} path
+     * @returns {TraversalState}
+     */
+    getState(path: string | SchemaLocation): TraversalState;
+    _debug(...args: any[]): void;
+    traverse(executor: any): any;
+}
+export type TraversalContextStandardOptions = {
+    strict?: boolean | undefined;
+    deep?: boolean | undefined;
+    debug?: boolean | undefined;
+};
+export type TraversalContextOptions = TraversalContextStandardOptions & {
+    [key: string]: any;
+};
+import { SchemaLocation } from '../schema-location.js';
+import { TraversalState } from './traversal-state.js';
+import { CompiledSchema } from "../compiled-schema.js";

package/types/traversal/traversal-state.d.ts

@@ -0,0 +1,97 @@
+export class TraversalState {
+    /**
+     * @param {TraversalContext} context
+     * @param {string} path
+     */
+    constructor(context: TraversalContext, path: string);
+    /** @type {{[key:string]:Executor}} */
+    executorCache: {
+        [key: string]: Executor<any>;
+    };
+    set completed(value: boolean);
+    get completed(): boolean;
+    get context(): TraversalContext;
+    get parent(): TraversalState | undefined;
+    get path(): string;
+    get name(): string;
+    get key(): string | number;
+    set location(location: SchemaLocation | undefined);
+    /** @type {SchemaLocation|undefined} */
+    get location(): SchemaLocation | undefined;
+    set schema(schema: CompiledSchema | undefined);
+    /** @type {CompiledSchema|undefined} */
+    get schema(): CompiledSchema | undefined;
+    set unionKey(key: string | undefined);
+    /** @type {string|undefined} */
+    get unionKey(): string | undefined;
+    set condition(condition: boolean | undefined);
+    /** @type {boolean|undefined} */
+    get condition(): boolean | undefined;
+    /**
+     * @param {string} propertyName
+     * @returns {TraversalState}
+     */
+    getChildState(propertyName: string): TraversalState;
+    getRelativeState(path: any): TraversalState | undefined;
+    set assignedInput(assignedInput: any);
+    get assignedInput(): any;
+    set value(value: any);
+    get value(): any;
+    set processed(value: boolean);
+    get processed(): boolean;
+    set input(input: any);
+    get input(): any;
+    set mandatory(value: boolean);
+    get mandatory(): boolean;
+    set pending(pending: any);
+    get pending(): any;
+    /**
+     * Sometimes transformers get called with a populated pending object.  If the transformed object isn't opaque,
+     * we can do a selective shallow copy over to the transformed object.
+     * @param {any} pending
+     * @param {any} value
+     * @package
+     */
+    copyPendingChildValues(pending: any, value: any): void;
+    invalidate(): void;
+    get isRequired(): boolean;
+    /** @type {boolean} */
+    get isComplete(): boolean;
+    get hasProcessedInput(): boolean;
+    get isPlaceholder(): boolean;
+    get hasChildren(): boolean;
+    get isContainer(): boolean;
+    get isPruned(): any;
+    get isDeep(): boolean;
+    get isOpaque(): boolean;
+    get isIncremental(): boolean;
+    get isStrict(): any;
+    get allowUnknown(): boolean;
+    get isUnion(): boolean;
+    get isUnresolved(): boolean;
+    get treatAsExplicit(): boolean;
+    get hasDescendentStates(): boolean;
+    get hasDescendentsToTraverse(): boolean;
+    get hasIncompleteDescendents(): boolean;
+    get incompleteDescendents(): TraversalState[];
+    findIncompleteChildNames(incomplete?: Set<any>): Set<any>;
+    listIncompleteChildren(): string[];
+    listPendingChildren(): string[];
+    invalidateChildren(): void;
+    get isEmptyPlaceholder(): boolean;
+    get needsInputProcessing(): boolean;
+    get hasWorkInProgress(): boolean;
+    /**
+     * Retrieve all incomplete child property states
+     *
+     * @type {Array<TraversalState>}
+     */
+    get activePropertyStates(): Array<TraversalState>;
+    get target(): any;
+    get options(): any;
+    #private;
+}
+import { Executor } from "../executor/executor.js";
+import { TraversalContext } from './traversal-context.js';
+import { SchemaLocation } from '../schema-location.js';
+import { CompiledSchema } from '../compiled-schema.js';

package/types/types.d.ts

@@ -0,0 +1,218 @@
+export type ISchema = {
+    /**
+     * - Base schema name for extension
+     */
+    base?: string | undefined;
+    /**
+     * - Schema properties
+     */
+    properties: ISchemaProperties;
+    /**
+     * - Schema options
+     */
+    options: ISchemaOptions;
+    /**
+     * - Schema metadata
+     */
+    metadata: ISchemaMetadata;
+    /**
+     * - Schema handlers
+     */
+    handlers: ISchemaHandlers;
+    /**
+     * - Union schema definitions
+     */
+    unionSchemas: ISchemaUnion;
+    /**
+     * - Serialize schema to plain object
+     */
+    toData: (schema: ISchema) => SchemaData | undefined;
+};
+export type ISchemaMetadataCommon = {
+    /**
+     * - help text description of the property; used by CommandLineSource
+     */
+    description?: string | undefined;
+    /**
+     * - help text type name of the property value; used by CommandLineSource
+     */
+    valueName?: string | undefined;
+    /**
+     * - help text description of the property value; used by CommandLineSource
+     */
+    valueDescription?: string | undefined;
+    /**
+     * - request a specific flag character; used by CommandLineSource
+     */
+    flagHint?: string | undefined;
+    /**
+     * - filter from basic help text; used by CommandLineSource
+     */
+    advanced?: boolean | undefined;
+    /**
+     * - hide from help; used by CommandLineSource
+     */
+    hidden?: boolean | undefined;
+    /**
+     * - mark this field for CommandLineSource to be used without a flag or option
+     */
+    general?: boolean | undefined;
+    /**
+     * - set to base/primitive types to help source parsers interpret values
+     */
+    parserTypeHint?: string | undefined;
+    /**
+     * - set to true to omit this schema's value when serializing
+     */
+    omitFromSerialize?: boolean | undefined;
+};
+export type ISchemaMetadata = ISchemaMetadataCommon & {
+    [key: string]: any;
+};
+export type SchemaFundamentalType = "any" | "string" | "number" | "boolean" | "bigint" | "symbol" | "object" | "array" | "function" | "buffer" | "null";
+export type ISchemaOptionsCommon = {
+    /**
+     * - should only be set on the core types supported by the schema
+     */
+    type?: SchemaFundamentalType | undefined;
+    /**
+     * - a function called during schema compilation
+     */
+    compileHook?: ((arg0: string, arg1: ISchema) => void) | undefined;
+    /**
+     * - whether an array type or string type can be empty
+     */
+    allowEmpty?: boolean | undefined;
+    /**
+     * - whether undefined values can be passed through this schema
+     */
+    allowUndefined?: boolean | undefined;
+    /**
+     * - whether to throw when a processor returns an Error, or treat it as a legal value
+     */
+    allowErrors?: boolean | undefined;
+    /**
+     * - when true, values are advisory (for expansion/metadata) and do not gate ensureAccepts
+     */
+    allowUnknownValues?: boolean | undefined;
+    /**
+     * - whether to do strict typechecking (defaults to true; must be explicitly false to be "lax")
+     */
+    strict?: boolean | undefined;
+    /**
+     * - disallow direct assignment; value will be inherited from a parent
+     */
+    reference?: boolean | undefined;
+    /**
+     * - flag indicating whether this field is required
+     */
+    required?: boolean | undefined;
+    /**
+     * - flag indicating that this field always returns the option value
+     */
+    literal?: boolean | undefined;
+    /**
+     * - flag indicating that this field exists implicitly in the post-transform value
+     */
+    implicit?: boolean | undefined;
+    /**
+     * - true/undefined means treat functional values as dynamic lookups; false means treat functions as values
+     */
+    dynamic?: boolean | undefined;
+    /**
+     * - triggers value to be copied to the context field with this name
+     */
+    context?: string | undefined;
+    /**
+     * - default value
+     */
+    default?: any;
+    /**
+     * - list of legal input values for this field (each is normalized during compilation)
+     */
+    values?: any[] | undefined;
+    /**
+     * - true if this schema acts as a selector
+     */
+    selector?: boolean | undefined;
+    /**
+     * - this schema activates if the selector matches the value, or matches this prop name if true
+     */
+    selection?: string | boolean | undefined;
+};
+export type ISchemaOptions = ISchemaOptionsCommon & {
+    [key: string]: any;
+};
+export type ISchemaHandlers = {
+    normalizers?: any[] | undefined;
+    conditions?: any[] | undefined;
+    transformers?: any[] | undefined;
+    serializers?: any[] | undefined;
+    unionDiscriminator?: ValueProcessorSpec;
+};
+export type ISchemaMetadataAttributesCommon = {
+    /**
+     * - help text description of the property; used by CommandLineSource
+     */
+    _description?: string | undefined;
+    /**
+     * - help text type name of the property value; used by CommandLineSource
+     */
+    _valueName?: string | undefined;
+    /**
+     * - help text description of the property value; used by CommandLineSource
+     */
+    _valueDescription?: string | undefined;
+    /**
+     * - request a specific flag character; used by CommandLineSource
+     */
+    _flagHint?: string | undefined;
+    /**
+     * - filter from basic help text; used by CommandLineSource
+     */
+    _advanced?: boolean | undefined;
+    /**
+     * - hide from help; used by CommandLineSource
+     */
+    _hidden?: boolean | undefined;
+    /**
+     * - mark this field for CommandLineSource to be used without a flag or option
+     */
+    _general?: boolean | undefined;
+    /**
+     * - set to base/primitive types to help source parsers interpret values
+     */
+    _parserTypeHint?: string | undefined;
+    /**
+     * - set to true to omit this schema's value when serializing
+     */
+    _omitFromSerialize?: boolean | undefined;
+};
+export type ISchemaAttributes = ISchemaOptionsCommon & ISchemaMetadataAttributesCommon & {
+    [key: string]: any;
+};
+export type ISchemaProperties = {
+    [key: string]: ISchema;
+};
+export type ISchemaUnion = {
+    [key: string]: ISchema;
+};
+export type SchemaData = {
+    base?: string | undefined;
+    properties?: {
+        [key: string]: SchemaData;
+    } | undefined;
+    handlers?: {
+        [key: string]: any;
+    } | undefined;
+    metadata?: {
+        [key: string]: string;
+    } | undefined;
+    options?: {
+        [key: string]: any;
+    } | undefined;
+    unionSchemas?: {
+        [key: string]: SchemaData;
+    } | undefined;
+};
+import type { ValueProcessorSpec } from './value-processor/value-processor.js';

package/types/value-processor/composed-value-processor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Wrap an existing executor as a ValueProcessor
+ *
+ * @augments {ValueProcessor}
+ */
+export class ComposedValueProcessor extends ValueProcessor {
+    /**
+     * @param {Executor<any>} executor
+     * @param {any} spec
+     * @param {string} [description]
+     */
+    constructor(executor: Executor<any>, spec: any, description?: string);
+    execute(value: any, target: any, location: any, options: any): any;
+    #private;
+}
+import { ValueProcessor } from './value-processor.js';
+import { Executor } from "../executor/executor.js";

package/types/value-processor/defined-value-processor.d.ts

@@ -0,0 +1,16 @@
+/** @import {ValueProcessorFunction, ValueProcessorDefinition, ValueProcessorArgs} from './value-processor.js' */
+/**
+ * @augments {ParameterizedValueProcessor}
+ */
+export class DefinedValueProcessor extends ParameterizedValueProcessor {
+    /**
+     * @param {ValueProcessorDefinition} definition
+     * @param {ValueProcessor[]|{[parameter:string]:ValueProcessor}} [args]
+     */
+    constructor(definition: ValueProcessorDefinition, args?: ValueProcessor[] | {
+        [parameter: string]: ValueProcessor;
+    });
+}
+import { ParameterizedValueProcessor } from './parameterized-value-processor.js';
+import type { ValueProcessorDefinition } from './value-processor.js';
+import { ValueProcessor } from './value-processor.js';

package/types/value-processor/function-value-processor.d.ts

@@ -0,0 +1,15 @@
+/** @import {ValueProcessorFunction, ValueProcessorDefinition, ValueProcessorArgs} from './value-processor.js' */
+/**
+ * @augments {ValueProcessor}
+ */
+export class FunctionValueProcessor extends ValueProcessor {
+    /**
+     * @param {ValueProcessorFunction} process
+     * @param {ValueProcessor} [args]
+     */
+    constructor(process: ValueProcessorFunction, args?: ValueProcessor);
+    spec: ValueProcessorFunction;
+    #private;
+}
+import { ValueProcessor } from './value-processor.js';
+import type { ValueProcessorFunction } from './value-processor.js';

package/types/value-processor/parameterized-value-processor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @augments {ValueProcessor}
+ */
+export class ParameterizedValueProcessor extends ValueProcessor {
+    /**
+     * @param {ValueProcessor} mainProcessor
+     * @param {ValueProcessor|undefined} argsProcessor
+     * @param {any} spec
+     * @param {string} [description]
+     */
+    constructor(mainProcessor: ValueProcessor, argsProcessor: ValueProcessor | undefined, spec: any, description?: string);
+    #private;
+}
+import { ValueProcessor } from './value-processor.js';

package/types/value-processor/parameters-value-processor.d.ts

@@ -0,0 +1,28 @@
+/** @typedef {[key:string, executor:Executor]} ObjectExecutorEntry */
+/**
+ * ParametersValueProcessor is an Executor that uses a list of parameter definitions to validate and execute
+ * provided argument Executors.
+ *
+ * Parameters are managed as follows:
+ * - The first optional parameter without an explicit default will use the pipeline value as its default.
+ * - If a type option is specified, that argument will be validated against that type.
+ * - Constant executors will be checked at construction.
+ * - If all parameters are passed constant executor arguments, the entire executor will be constant.
+ * - Receiving "undefined" as an argument value at runtime should not be interpreted as a missing argument,
+ *   as it may simply indicate that the value is not yet available (but may become available later.)
+ *
+ * @augments {ValueProcessor}
+ */
+export class ParametersValueProcessor extends ValueProcessor {
+    /**
+     * @param {object[]} [parameters]
+     * @param {ValueProcessor[]|{[parameter:string]:ValueProcessor}} [argsProcessors]
+     */
+    constructor(parameters?: object[], argsProcessors?: ValueProcessor[] | {
+        [parameter: string]: ValueProcessor;
+    });
+    #private;
+}
+export type ObjectExecutorEntry = [key: string, executor: Executor<any>];
+import { ValueProcessor } from './value-processor.js';
+import { Executor } from '../executor/executor.js';

package/types/value-processor/spec.d.ts

@@ -0,0 +1,22 @@
+/** @import { ValueProcessorSpec, KeywordValueProcessorSpec } from './value-processor.js' */
+/**
+ * @param {ValueProcessorSpec} spec
+ * @returns {spec is KeywordValueProcessorSpec}
+ * @package
+ */
+export function isKeywordValueProcessorSpec(spec: ValueProcessorSpec): spec is KeywordValueProcessorSpec;
+/**
+ * @param {KeywordValueProcessorSpec} keywordSpec
+ * @returns {[string,any]}
+ * @package
+ */
+export function extractKeywordValueProcessorSpec(keywordSpec: KeywordValueProcessorSpec): [string, any];
+/**
+ * Check whether a candidate spec is legal
+ * @param {any} spec
+ * @returns {boolean}
+ * @package
+ */
+export function isLegalValueProcessorSpec(spec: any): boolean;
+import type { ValueProcessorSpec } from './value-processor.js';
+import type { KeywordValueProcessorSpec } from './value-processor.js';