@mirascript/typed 0.1.76 → 0.1.79

package/src/json/record.ts

@@ -0,0 +1,70 @@
+import type { JSONSchema } from 'json-schema-typed';
+import type { RecordField, RecordType, Type } from '../parser.js';
+import { toJSONSchemaImpl, type ToJSONSchemaOptionsImpl } from './impl.js';
+import { templatePartPattern, RE_ANY } from './template.js';
+import { isLiteralType } from './literal.js';
+
+/** Convert fields record into JSON Schema */
+function fieldsRecord(fields: readonly RecordField[], options: ToJSONSchemaOptionsImpl): JSONSchema {
+    const properties: Record<string, JSONSchema> = {};
+    const required: string[] = [];
+    for (const field of fields) {
+        properties[field.name] = toJSONSchemaImpl(field.type, options);
+        if (!options.loose && !field.optional) {
+            required.push(field.name);
+        }
+    }
+    const schema: JSONSchema = {
+        type: 'object',
+        properties,
+        additionalProperties: options.loose,
+    };
+    if (required.length > 0) {
+        schema.required = required;
+    }
+    return schema;
+}
+
+/** Convert generic record into JSON Schema */
+function genericRecord(key: Type, value: Type, options: ToJSONSchemaOptionsImpl): JSONSchema {
+    const valueSchema = toJSONSchemaImpl(value, options);
+
+    if (typeof key == 'object') {
+        if (isLiteralType(key)) {
+            const schema: JSONSchema = {
+                type: 'object',
+                properties: { [String(key.value)]: valueSchema },
+                additionalProperties: options.loose,
+            };
+            return schema;
+        } else if (key.kind === 'union' && key.types.every(isLiteralType)) {
+            const schema: JSONSchema = {
+                type: 'object',
+                properties: Object.fromEntries(key.types.map((t) => [String(t.value), valueSchema])),
+                additionalProperties: options.loose,
+            };
+            return schema;
+        }
+    }
+    const pattern = templatePartPattern(key, false);
+    if (pattern === RE_ANY) {
+        return {
+            type: 'object',
+            additionalProperties: valueSchema,
+        };
+    }
+    const schema: JSONSchema = {
+        type: 'object',
+        patternProperties: { [`^${pattern}$`]: valueSchema },
+        additionalProperties: options.loose,
+    };
+    return schema;
+}
+
+/** Converts a RecordType into JSON Schema */
+export function record(simplified: RecordType, options: ToJSONSchemaOptionsImpl): JSONSchema {
+    if ('fields' in simplified) {
+        return fieldsRecord(simplified.fields, options);
+    }
+    return genericRecord(simplified.key ?? 'string', simplified.value, options);
+}

package/src/json/string.ts

@@ -0,0 +1,30 @@
+import type { JSONSchema } from 'json-schema-typed';
+import type { KnownType, NamedType } from '../parser.js';
+
+/** Converts a KnownType or NamedType into JSON Schema */
+export function string(type: KnownType | NamedType): JSONSchema {
+    switch (type) {
+        case 'string':
+            return { type: 'string' };
+        case 'number':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'nil':
+            return { type: 'null' };
+        case 'array':
+            return { type: 'array', items: true };
+        case 'record':
+            return { type: 'object' };
+        case 'extern':
+            return true;
+        case 'any':
+            return true;
+        case 'unknown':
+            return true;
+        case 'never':
+            return false;
+        default:
+            return true;
+    }
+}

package/src/json/template.ts

@@ -0,0 +1,71 @@
+import type { JSONSchema } from 'json-schema-typed';
+import { REG_NUMBER } from '@mirascript/constants';
+import type { TemplateType, Type } from '../parser.js';
+
+/** Escapes a literal string for use in a regular expression */
+function escapeRegex(value: string): string {
+    return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+export const RE_ANY = '.*?';
+const RE_NUMBER = REG_NUMBER.source;
+const RE_BOOLEAN = 'true|false';
+
+/** Converts a template interpolation part into a regex pattern fragment */
+function templatePartPatternImpl(part: Type): string {
+    if (typeof part == 'symbol') {
+        return RE_ANY;
+    }
+    if (typeof part == 'string') {
+        if (part === 'number') return RE_NUMBER;
+        if (part === 'boolean') return RE_BOOLEAN;
+        if (part === 'nil' || part === 'never') return '';
+        return RE_ANY;
+    }
+    if (part.kind === 'literal') {
+        if (typeof part.value === 'boolean') {
+            return String(part.value);
+        } else {
+            return escapeRegex(part.value);
+        }
+    }
+    if (part.kind === 'union') {
+        const patterns = new Set(part.types.map((p) => templatePartPatternImpl(p)));
+        if (patterns.has(RE_ANY)) {
+            return RE_ANY;
+        } else {
+            const hasEmpty = patterns.delete('');
+            let result = Array.from(patterns).join('|');
+            if (hasEmpty) {
+                result = `(${result})?`;
+            }
+            return result;
+        }
+    }
+    if (part.kind === 'intersection') {
+        // Regex intersection is not representable in general; keep behavior conservative.
+        return RE_ANY;
+    }
+    return RE_ANY;
+}
+
+/** Converts a template interpolation part into a regex pattern fragment */
+export function templatePartPattern(part: Type, grouping: boolean): string {
+    const result = templatePartPatternImpl(part);
+    if (!grouping) return result;
+    if (result.startsWith('(')) return result;
+    return `(${result})`;
+}
+
+/** Converts a TemplateType into a JSON Schema pattern */
+export function template(type: TemplateType): JSONSchema {
+    const pattern = `^${type.parts
+        .map((p) => {
+            if (typeof p == 'object' && p.kind === 'literal' && typeof p.value === 'string') {
+                return templatePartPattern(p, false);
+            }
+            return templatePartPattern(p, true);
+        })
+        .join('')}$`;
+    return { type: 'string', pattern };
+}

package/src/json/tuple.ts

@@ -0,0 +1,52 @@
+import type { JSONSchema } from 'json-schema-typed';
+import type { TupleType } from '../parser.js';
+import { toJSONSchemaImpl, type ToJSONSchemaOptionsImpl } from './impl.js';
+
+/**
+ * Converts a TupleType into JSON Schema
+ */
+export function tuple(tuple: TupleType, options: ToJSONSchemaOptionsImpl): JSONSchema {
+    // Collect element schemas, unwrapping array from rest elements (..T[] → T).
+    // Non-array rest (e.g. ..string) is treated as any ({}).
+    const elementSchemas = tuple.elements.map((e) => {
+        const t = e.type;
+        if (!e.spread) return toJSONSchemaImpl(t, options);
+        if (typeof t == 'object' && t.kind === 'array') {
+            return toJSONSchemaImpl(t.element, options);
+        }
+        return true;
+    });
+
+    const prefixItems = [];
+    let i = 0;
+    for (; i < elementSchemas.length; i++) {
+        const el = tuple.elements[i]!;
+        if (el.spread) break;
+        prefixItems.push(elementSchemas[i]!);
+    }
+
+    const items = [];
+    let hasAny = false;
+    for (; i < elementSchemas.length; i++) {
+        const schema = elementSchemas[i]!;
+        items.push(schema);
+        if (schema === true) {
+            hasAny = true;
+        }
+    }
+
+    const schema: JSONSchema = { type: 'array' };
+    if (prefixItems.length > 0) {
+        schema.prefixItems = prefixItems;
+    }
+    if (hasAny) {
+        schema.items = true;
+    } else if (items.length > 1) {
+        schema.items = { anyOf: items };
+    } else if (items.length === 1) {
+        schema.items = items[0]!;
+    } else {
+        schema.items = options.loose;
+    }
+    return schema;
+}

package/src/json/union-intersection.ts

@@ -0,0 +1,43 @@
+import type { JSONSchema } from 'json-schema-typed';
+import type { IntersectionType, LiteralType, UnionType } from '../parser.js';
+import { type ToJSONSchemaOptionsImpl, toJSONSchemaImpl } from './impl.js';
+import { isLiteralType, literalEnum } from './literal.js';
+
+/** Converts a union type to JSON representation */
+export function union(union: UnionType, options: ToJSONSchemaOptionsImpl): JSONSchema {
+    const anyOf: JSONSchema[] = [];
+    const literals: LiteralType[] = [];
+    for (const t of union.types) {
+        if (isLiteralType(t)) {
+            literals.push(t);
+            continue;
+        }
+        const child = toJSONSchemaImpl(t, options);
+        if (child === true) {
+            return true;
+        }
+        if (child === false) {
+            continue;
+        }
+        anyOf.push(child);
+    }
+    if (literals.length > 0) {
+        anyOf.push(literalEnum(literals));
+    }
+    if (anyOf.length === 0) {
+        return false;
+    }
+    if (anyOf.length === 1) {
+        return anyOf[0]!;
+    }
+    return { anyOf };
+}
+
+/** Converts an intersection type to JSON representation */
+export function intersection(intersection: IntersectionType, options: ToJSONSchemaOptionsImpl): JSONSchema {
+    const allOf = intersection.types.map((t) => toJSONSchemaImpl(t, options));
+    if (allOf.length === 1) {
+        return allOf[0]!;
+    }
+    return { allOf };
+}

package/src/simplifier/dedup.ts

@@ -0,0 +1,61 @@
+import type { Type } from '../parser.js';
+
+/** Builds a stable key for type-level deduplication within one simplify call. */
+function getTypeDedupKey(type: Type, symbols: Map<symbol, number>): string {
+    if (typeof type === 'string') return `string:${type}`;
+    if (typeof type === 'symbol') {
+        const existing = symbols.get(type);
+        if (existing != null) return `symbol:${existing}`;
+        const next = symbols.size + 1;
+        symbols.set(type, next);
+        return `symbol:${next}`;
+    }
+    switch (type.kind) {
+        case 'array':
+            return `array:${getTypeDedupKey(type.element, symbols)}`;
+        case 'union':
+            return `union:[${type.types.map((t) => getTypeDedupKey(t, symbols)).join(',')}]`;
+        case 'intersection':
+            return `intersection:[${type.types.map((t) => getTypeDedupKey(t, symbols)).join(',')}]`;
+        case 'record':
+            if ('fields' in type) {
+                return `recordFields:[${type.fields
+                    .map((f) => `${f.name}:${String(Boolean(f.optional))}:${getTypeDedupKey(f.type, symbols)}`)
+                    .join(',')}]`;
+            }
+            return `recordKV:${type.key == null ? 'none' : getTypeDedupKey(type.key, symbols)}:${getTypeDedupKey(type.value, symbols)}`;
+        case 'literal':
+            return `literal:${typeof type.value}:${String(type.value)}`;
+        case 'template':
+            return `template:[${type.parts.map((p) => getTypeDedupKey(p, symbols)).join(',')}]`;
+        case 'function':
+            return `function:${
+                type.name ?? ''
+            }:<${(type.typeParams ?? []).map((p) => getTypeDedupKey(p, symbols)).join(',')}>(${type.params
+                .map((p) => `${p.name}:${String(Boolean(p.spread))}:${getTypeDedupKey(p.type, symbols)}`)
+                .join(',')})=>${type.returns == null ? 'void' : getTypeDedupKey(type.returns, symbols)}`;
+        case 'tuple':
+            return `tuple:[${type.elements
+                .map((e) => `${String(Boolean(e.spread))}:${getTypeDedupKey(e.type, symbols)}`)
+                .join(',')}]`;
+        case 'reflection':
+            return `reflection:${type.name}`;
+        default:
+            return 'unknown';
+    }
+}
+
+/** Removes duplicate members from union/intersection type member lists. */
+export function deduplicateTypeMembers(types: Type[]): Type[] {
+    if (types.length <= 1) return types;
+    const symbols = new Map<symbol, number>();
+    const seen = new Set<string>();
+    const result: Type[] = [];
+    for (const type of types) {
+        const key = getTypeDedupKey(type, symbols);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        result.push(type);
+    }
+    return result;
+}

package/src/simplifier/impl.ts

@@ -0,0 +1,64 @@
+import type { Type } from '../parser.js';
+import { simplifyIntersection } from './intersection.js';
+import type { SimplifyOptions } from './index.js';
+import { simplifyUnion } from './union.js';
+import { simplifyRecord } from './record.js';
+import { simplifyTuple } from './tuple.js';
+
+/** Options for simplifyImpl */
+export type SimplifyImplOptions = Required<SimplifyOptions>;
+
+/** Simplifies a Type AST in place, optionally disabling individual normalization passes. */
+export function simplifyImpl(type: Type, options: SimplifyImplOptions): Type {
+    if (typeof type == 'symbol' || typeof type == 'string') {
+        return type;
+    }
+
+    if (type.kind === 'array') {
+        type.element = simplifyImpl(type.element, options);
+        if (options.normalizeGenericArray && (type.element === 'any' || type.element === 'unknown')) {
+            return 'array';
+        }
+        return type;
+    }
+
+    if (type.kind === 'function') {
+        for (const param of type.params) {
+            param.type = simplifyImpl(param.type, options);
+        }
+        if (type.returns != null) type.returns = simplifyImpl(type.returns, options);
+        return type;
+    }
+
+    if (type.kind === 'literal') {
+        return type;
+    }
+
+    if (type.kind === 'template') {
+        type.parts = type.parts.map((part) => simplifyImpl(part, options));
+        return type;
+    }
+
+    if (type.kind === 'tuple') {
+        return simplifyTuple(type, options);
+    }
+
+    if (type.kind === 'reflection') {
+        return type;
+    }
+
+    if (type.kind === 'record') {
+        return simplifyRecord(type, options);
+    }
+
+    if (type.kind === 'union') {
+        return simplifyUnion(type, options);
+    }
+
+    if (type.kind === 'intersection') {
+        return simplifyIntersection(type, options);
+    }
+    /* c8 ignore next 3 */
+    (type) satisfies never;
+    return type;
+}

package/src/simplifier/index.ts

@@ -0,0 +1,67 @@
+import type { Type } from '../parser.js';
+import { simplifyImpl } from './impl.js';
+import type { TopType } from './top-type.js';
+
+/** Controls which type simplifications are applied. */
+export interface SimplifyOptions {
+    /** Flatten nested union nodes. */
+    flattenUnions?: boolean;
+    /** Flatten nested intersection nodes. */
+    flattenIntersections?: boolean;
+    /** Remove duplicate members inside union nodes. */
+    deduplicateUnions?: boolean;
+    /** Remove duplicate members inside intersection nodes. */
+    deduplicateIntersections?: boolean;
+    /** Remove single-member union nodes. */
+    unwrapSingleUnion?: boolean;
+    /** Remove single-member intersection nodes. */
+    unwrapSingleIntersection?: boolean;
+    /** Distribute intersections over unions. */
+    distributeIntersectionsOverUnions?: boolean;
+    /** Merge intersections of explicit record fields. */
+    mergeRecordIntersections?: boolean;
+    /** Inline tuple spread elements (..[A, B] → A, B). */
+    expandTupleSpreads?: boolean;
+    /**
+     * Eliminate / absorb top types in unions.
+     * - `unknown | T` → `unknown`
+     * - `any | T` → `any`
+     * - `T | never` → `T`
+     * `true` enables all, or pass a subset of `'unknown' | 'never' | 'any'`.
+     */
+    simplifyTopTypesInUnions?: boolean | TopType[];
+    /**
+     * Eliminate / absorb top types in intersections.
+     * - `never & T` → `never`
+     * - `T & unknown` → `T`
+     * - `T & any` → `T`
+     * `true` enables all, or pass a subset of `'unknown' | 'never' | 'any'`.
+     */
+    simplifyTopTypesInIntersections?: boolean | TopType[];
+    /** `record<string, V>` → `record<V>` (string is the default key). */
+    normalizeGenericRecord?: boolean;
+    /** `array<any | unknown>` → `array` (no element constraint). */
+    normalizeGenericArray?: boolean;
+}
+
+const DEFAULT_OPTIONS: Required<SimplifyOptions> = {
+    flattenUnions: true,
+    flattenIntersections: true,
+    deduplicateUnions: true,
+    deduplicateIntersections: true,
+    unwrapSingleUnion: true,
+    unwrapSingleIntersection: true,
+    distributeIntersectionsOverUnions: true,
+    mergeRecordIntersections: true,
+    expandTupleSpreads: true,
+    simplifyTopTypesInUnions: true,
+    simplifyTopTypesInIntersections: true,
+    normalizeGenericRecord: true,
+    normalizeGenericArray: true,
+};
+
+/** Simplifies a Type AST in place, optionally disabling individual normalization passes. */
+export function simplify(type: Type, options?: SimplifyOptions): Type {
+    const config = { ...DEFAULT_OPTIONS, ...options };
+    return simplifyImpl(type, config);
+}

package/src/simplifier/intersection.ts

@@ -0,0 +1,129 @@
+import type { IntersectionType, Type, RecordType, RecordField } from '../parser.js';
+import { deduplicateTypeMembers } from './dedup.js';
+import { type SimplifyImplOptions, simplifyImpl } from './impl.js';
+import { resolveTopTypes } from './top-type.js';
+import { isFieldRecordType, isUnionType, isIntersectionType } from './utils.js';
+
+/** Merges explicit record fields across an intersection. */
+function mergeRecordFieldIntersections(types: Array<Extract<RecordType, { fields: RecordField[] }>>): Type {
+    const merged = new Map<string, { optional: boolean; type: Type }>();
+    for (const record of types) {
+        for (const field of record.fields) {
+            const prev = merged.get(field.name);
+            if (prev == null) {
+                merged.set(field.name, {
+                    optional: field.optional ?? false,
+                    type: field.type,
+                });
+                continue;
+            }
+            merged.set(field.name, {
+                optional: (prev.optional ?? false) && (field.optional ?? false),
+                type: {
+                    kind: 'intersection',
+                    types: [prev.type, field.type],
+                },
+            });
+        }
+    }
+
+    return {
+        kind: 'record',
+        fields: Array.from(merged.entries()).map(([name, field]) => ({
+            name,
+            optional: field.optional,
+            type: field.type,
+        })),
+    };
+}
+
+/** Flattens nested intersection nodes when the corresponding option is enabled. */
+function flattenIntersectionTypes(type: IntersectionType, options: SimplifyImplOptions): Type[] {
+    const types = type.types.map((item) => simplifyImpl(item, options));
+    if (!options.flattenIntersections) return types;
+    const result: Type[] = [];
+    for (const type of types) {
+        if (isIntersectionType(type)) {
+            result.push(...flattenIntersectionTypes(type, options));
+        } else {
+            result.push(type);
+        }
+    }
+    return result;
+}
+
+/** Distributes intersections over unions using a cartesian product. */
+function distributeIntersectionsOverUnions(types: Type[], options: SimplifyImplOptions): Type {
+    let combinations: Type[][] = [[]];
+    for (const type of types) {
+        const choices = isUnionType(type) ? type.types : [type];
+        const next: Type[][] = [];
+        for (const combo of combinations) {
+            for (const choice of choices) {
+                next.push([...combo, choice]);
+            }
+        }
+        combinations = next;
+    }
+
+    const opt = { ...options, distributeIntersectionsOverUnions: false };
+    const branches = combinations.map((combination) => simplifyImpl({ kind: 'intersection', types: combination }, opt));
+    if (branches.length === 1) return branches[0]!;
+    return { kind: 'union', types: branches };
+}
+
+/** Simplifies an intersection type */
+export function simplifyIntersection(type: IntersectionType, options: SimplifyImplOptions): Type {
+    let simplifiedTypes = flattenIntersectionTypes(type, options);
+
+    // Top-type elimination: never & T → never, T & unknown → T, T & any → T
+    const topTypes = resolveTopTypes(options.simplifyTopTypesInIntersections);
+    if (topTypes.length > 0) {
+        const typeNames = new Set(simplifiedTypes.filter((t): t is string => typeof t === 'string'));
+        if (topTypes.includes('never') && typeNames.has('never')) return 'never';
+        let filtered = false;
+        if (topTypes.includes('unknown') && typeNames.has('unknown')) {
+            simplifiedTypes = simplifiedTypes.filter((t) => t !== 'unknown');
+            filtered = true;
+        }
+        if (topTypes.includes('any') && typeNames.has('any')) {
+            simplifiedTypes = simplifiedTypes.filter((t) => t !== 'any');
+            filtered = true;
+        }
+        if (filtered) {
+            if (simplifiedTypes.length === 1) return simplifiedTypes[0]!;
+            if (simplifiedTypes.length === 0) {
+                // All members were the same eliminated top type
+                return typeNames.has('any') ? 'any' : 'unknown';
+            }
+        }
+    }
+
+    if (options.deduplicateIntersections) {
+        simplifiedTypes = deduplicateTypeMembers(simplifiedTypes);
+    }
+    if (options.distributeIntersectionsOverUnions && simplifiedTypes.some(isUnionType)) {
+        return distributeIntersectionsOverUnions(simplifiedTypes, options);
+    }
+    if (options.mergeRecordIntersections) {
+        const recordTypes = simplifiedTypes.filter(isFieldRecordType);
+        if (recordTypes.length >= 2) {
+            const nonRecordTypes = simplifiedTypes.filter((item) => !isFieldRecordType(item));
+            const mergedRecord = simplifyImpl(mergeRecordFieldIntersections(recordTypes), options);
+            let mergedTypes = [mergedRecord, ...nonRecordTypes];
+            if (options.deduplicateIntersections) {
+                mergedTypes = deduplicateTypeMembers(mergedTypes);
+            }
+            if (options.unwrapSingleIntersection && mergedTypes.length === 1) {
+                return mergedTypes[0]!;
+            }
+            type.types = mergedTypes;
+            return type;
+        }
+    }
+    if (options.unwrapSingleIntersection && simplifiedTypes.length === 1) {
+        return simplifiedTypes[0]!;
+    }
+    type.types = simplifiedTypes;
+    return type;
+}

package/src/simplifier/record.ts

@@ -0,0 +1,24 @@
+import type { RecordField, RecordType } from '../parser.js';
+import { type SimplifyImplOptions, simplifyImpl } from './impl.js';
+
+/** Simplifies a record field recursively. */
+function simplifyRecordField(field: RecordField, options: SimplifyImplOptions): RecordField {
+    return {
+        ...field,
+        type: simplifyImpl(field.type, options),
+    };
+}
+
+/** Simplifies a record recursively. */
+export function simplifyRecord(record: RecordType, options: SimplifyImplOptions): RecordType {
+    if ('fields' in record) {
+        record.fields = record.fields.map((field) => simplifyRecordField(field, options));
+    } else {
+        if (record.key != null) record.key = simplifyImpl(record.key, options);
+        record.value = simplifyImpl(record.value, options);
+        if (options.normalizeGenericRecord && record.key === 'string') {
+            delete record.key;
+        }
+    }
+    return record;
+}

package/src/simplifier/top-type.ts

@@ -0,0 +1,9 @@
+/** Top types that can be absorbed / eliminated in simplification. */
+export type TopType = 'unknown' | 'never' | 'any';
+
+/** Resolves the top types option into an array of top types. */
+export function resolveTopTypes(value: boolean | TopType[] | undefined): TopType[] {
+    if (value === false || value == null) return [];
+    if (value === true) return ['unknown', 'never', 'any'];
+    return value;
+}

package/src/simplifier/tuple.ts

@@ -0,0 +1,20 @@
+import type { TupleType } from '../parser.js';
+import { simplifyImpl, type SimplifyImplOptions } from './impl.js';
+
+/** Simplifies tuple types */
+export function simplifyTuple(type: TupleType, options: SimplifyImplOptions): TupleType {
+    type.elements = type.elements.flatMap((element) => {
+        const simplifiedType = simplifyImpl(element.type, options);
+        if (
+            options.expandTupleSpreads &&
+            element.spread &&
+            typeof simplifiedType == 'object' &&
+            simplifiedType.kind === 'tuple'
+        ) {
+            // Inline tuple spread: ..[A, B] → A, B
+            return simplifiedType.elements;
+        }
+        return [{ ...element, type: simplifiedType }];
+    });
+    return type;
+}