@typescript-eslint/rule-schema-to-typescript-types 0.0.0 → 8.45.1-alpha.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 typescript-eslint and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# `@typescript-eslint/rule-schema-to-typescript-types`
+
+> Tool for generating TypeScript type definitions from a rule's options schema
+
+## ✋ Internal Package
+
+This is an _internal package_ to the [typescript-eslint monorepo](https://github.com/typescript-eslint/typescript-eslint).
+
+👉 See **https://typescript-eslint.io** for docs on typescript-eslint.

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class NotSupportedError extends Error {
+    constructor(thing: string, target: unknown);
+}
+export declare class UnexpectedError extends Error {
+    constructor(error: string, target: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+export class NotSupportedError extends Error {
+    constructor(thing, target) {
+        super(`Generating a type for ${thing} is not currently supported:\n${JSON.stringify(target, null, 2)}`);
+    }
+}
+export class UnexpectedError extends Error {
+    constructor(error, target) {
+        super(`Unexpected Error: ${error}:\n${JSON.stringify(target, null, 2)}`);
+    }
+}

package/dist/generateArrayType.d.ts

@@ -0,0 +1,3 @@
+import type { JSONSchema4ArraySchema } from '@typescript-eslint/utils/json-schema';
+import type { ArrayAST, RefMap, TupleAST, UnionAST } from './types.js';
+export declare function generateArrayType(schema: JSONSchema4ArraySchema, refMap: RefMap): ArrayAST | TupleAST | UnionAST;

package/dist/generateArrayType.js

@@ -0,0 +1,107 @@
+import { TSUtils } from '@typescript-eslint/utils';
+import { NotSupportedError, UnexpectedError } from './errors.js';
+import { generateType } from './generateType.js';
+import { getCommentLines } from './getCommentLines.js';
+/**
+ * If there are more than 20 tuple items then we will not make it a tuple type
+ * and instead will just make it an array type for brevity
+ */
+const MAX_ITEMS_TO_TUPLIZE = 20;
+export function generateArrayType(schema, refMap) {
+    if (!schema.items) {
+        // it's technically valid to declare things like {type: 'array'} -> any[]
+        // but that's obviously dumb and loose so let's not even bother with it
+        throw new UnexpectedError('Unexpected missing items', schema);
+    }
+    if (!TSUtils.isArray(schema.items) && schema.additionalItems) {
+        throw new NotSupportedError('singlely-typed array with additionalItems', schema);
+    }
+    const commentLines = getCommentLines(schema);
+    const minItems = schema.minItems ?? 0;
+    const maxItems = schema.maxItems != null && schema.maxItems < MAX_ITEMS_TO_TUPLIZE
+        ? schema.maxItems
+        : -1;
+    const hasMaxItems = maxItems >= 0;
+    if (!TSUtils.isArray(schema.items)) {
+        // While we could support `minItems` and `maxItems` with tuple types,
+        // for example `[T, ...T[]]`, it harms readability for documentation purposes.
+        // See https://github.com/typescript-eslint/typescript-eslint/issues/11117
+        return {
+            commentLines,
+            elementType: generateType(schema.items, refMap),
+            type: 'array',
+        };
+    }
+    // treat as a tuple
+    const items = schema.items;
+    let spreadItemSchema = null;
+    if (hasMaxItems && items.length < maxItems) {
+        spreadItemSchema =
+            typeof schema.additionalItems === 'object'
+                ? schema.additionalItems
+                : { type: 'any' };
+    }
+    // quick validation so we generate sensible types
+    if (hasMaxItems && maxItems < items.length) {
+        throw new UnexpectedError(`maxItems (${maxItems}) is smaller than the number of items schemas provided (${items.length})`, schema);
+    }
+    if (maxItems > items.length && spreadItemSchema == null) {
+        throw new UnexpectedError('maxItems is larger than the number of items schemas, but there was not an additionalItems schema provided', schema);
+    }
+    const itemTypes = items.map(i => generateType(i, refMap));
+    const spreadItem = spreadItemSchema == null ? null : generateType(spreadItemSchema, refMap);
+    if (itemTypes.length > minItems) {
+        /*
+        if there are more items than the min, we return a union of tuples instead of
+        using the optional element operator. This is done because it is more type-safe.
+    
+        // optional element operator
+        type A = [string, string?, string?]
+        const a: A = ['a', undefined, 'c'] // no error
+    
+        // union of tuples
+        type B = [string] | [string, string] | [string, string, string]
+        const b: B = ['a', undefined, 'c'] // TS error
+        */
+        const cumulativeTypesList = itemTypes.slice(0, minItems);
+        const typesToUnion = [];
+        if (cumulativeTypesList.length > 0) {
+            // actually has minItems, so add the initial state
+            typesToUnion.push(createTupleType(cumulativeTypesList));
+        }
+        else {
+            // no minItems means it's acceptable to have an empty tuple type
+            typesToUnion.push(createTupleType([]));
+        }
+        for (let i = minItems; i < itemTypes.length; i += 1) {
+            cumulativeTypesList.push(itemTypes[i]);
+            if (i === itemTypes.length - 1) {
+                // only the last item in the union should have the spread parameter
+                typesToUnion.push(createTupleType(cumulativeTypesList, spreadItem));
+            }
+            else {
+                typesToUnion.push(createTupleType(cumulativeTypesList));
+            }
+        }
+        return {
+            commentLines,
+            elements: typesToUnion,
+            type: 'union',
+        };
+    }
+    return {
+        commentLines,
+        elements: itemTypes,
+        spreadType: spreadItem,
+        type: 'tuple',
+    };
+}
+function createTupleType(elements, spreadType = null) {
+    return {
+        type: 'tuple',
+        // clone the array because we know we'll keep mutating it
+        commentLines: [],
+        elements: [...elements],
+        spreadType,
+    };
+}

package/dist/generateObjectType.d.ts

@@ -0,0 +1,3 @@
+import type { JSONSchema4ObjectSchema } from '@typescript-eslint/utils/json-schema';
+import type { ObjectAST, RefMap } from './types.js';
+export declare function generateObjectType(schema: JSONSchema4ObjectSchema, refMap: RefMap): ObjectAST;

package/dist/generateObjectType.js

@@ -0,0 +1,43 @@
+import { requiresQuoting } from '@typescript-eslint/type-utils';
+import { TSUtils } from '@typescript-eslint/utils';
+import { generateType } from './generateType.js';
+import { getCommentLines } from './getCommentLines.js';
+export function generateObjectType(schema, refMap) {
+    const commentLines = getCommentLines(schema);
+    let indexSignature = null;
+    if (schema.additionalProperties === true ||
+        // eslint-disable-next-line @typescript-eslint/internal/eqeq-nullish
+        schema.additionalProperties === undefined) {
+        indexSignature = {
+            commentLines: [],
+            type: 'type-reference',
+            typeName: 'unknown',
+        };
+    }
+    else if (typeof schema.additionalProperties === 'object') {
+        const indexSigType = generateType(schema.additionalProperties, refMap);
+        indexSignature = indexSigType;
+    }
+    const properties = [];
+    const required = new Set(TSUtils.isArray(schema.required) ? schema.required : []);
+    if (schema.properties) {
+        const propertyDefs = Object.entries(schema.properties);
+        for (const [propName, propSchema] of propertyDefs) {
+            const propType = generateType(propSchema, refMap);
+            const sanitisedPropName = requiresQuoting(propName)
+                ? `'${propName}'`
+                : propName;
+            properties.push({
+                name: sanitisedPropName,
+                optional: !required.has(propName),
+                type: propType,
+            });
+        }
+    }
+    return {
+        commentLines,
+        indexSignature,
+        properties,
+        type: 'object',
+    };
+}

package/dist/generateType.d.ts

@@ -0,0 +1,3 @@
+import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema';
+import type { SchemaAST, RefMap } from './types.js';
+export declare function generateType(schema: JSONSchema4, refMap: RefMap): SchemaAST;

package/dist/generateType.js

@@ -0,0 +1,99 @@
+import { TSUtils } from '@typescript-eslint/utils';
+import { NotSupportedError, UnexpectedError } from './errors.js';
+import { generateArrayType } from './generateArrayType.js';
+import { generateObjectType } from './generateObjectType.js';
+import { generateUnionType } from './generateUnionType.js';
+import { getCommentLines } from './getCommentLines.js';
+// keywords we probably should support but currently do not support
+const UNSUPPORTED_KEYWORDS = new Set([
+    'allOf',
+    'dependencies',
+    'extends',
+    'maxProperties',
+    'minProperties',
+    'multipleOf',
+    'not',
+    'patternProperties',
+]);
+export function generateType(schema, refMap) {
+    const unsupportedProps = Object.keys(schema).filter(key => UNSUPPORTED_KEYWORDS.has(key));
+    if (unsupportedProps.length > 0) {
+        throw new NotSupportedError(unsupportedProps.join(','), schema);
+    }
+    const commentLines = getCommentLines(schema);
+    if (schema.$ref) {
+        const refName = refMap.get(schema.$ref);
+        if (refName == null) {
+            throw new UnexpectedError(`Could not find definition for $ref ${schema.$ref}.\nAvailable refs:\n${[...refMap.keys()].join('\n')})`, schema);
+        }
+        return {
+            commentLines,
+            type: 'type-reference',
+            typeName: refName,
+        };
+    }
+    if ('enum' in schema && schema.enum) {
+        return {
+            ...generateUnionType(schema.enum, refMap),
+            commentLines,
+        };
+    }
+    if ('anyOf' in schema && schema.anyOf) {
+        return {
+            // a union isn't *TECHNICALLY* correct - technically anyOf is actually
+            // anyOf: [T, U, V] -> T | U | V | T & U | T & V | U & V
+            // in practice though it is most used to emulate a oneOf
+            ...generateUnionType(schema.anyOf, refMap),
+            commentLines,
+        };
+    }
+    if ('oneOf' in schema && schema.oneOf) {
+        return {
+            ...generateUnionType(schema.oneOf, refMap),
+            commentLines,
+        };
+    }
+    if (!('type' in schema) || schema.type == null) {
+        throw new NotSupportedError('untyped schemas without one of [$ref, enum, oneOf]', schema);
+    }
+    if (TSUtils.isArray(schema.type)) {
+        throw new NotSupportedError('schemas with multiple types', schema);
+    }
+    switch (schema.type) {
+        case 'any':
+            return {
+                commentLines,
+                type: 'type-reference',
+                typeName: 'unknown',
+            };
+        case 'null':
+            return {
+                commentLines,
+                type: 'type-reference',
+                typeName: 'null',
+            };
+        case 'number':
+        case 'string':
+            return {
+                code: schema.type,
+                commentLines,
+                type: 'literal',
+            };
+        case 'array':
+            return generateArrayType(schema, refMap);
+        case 'boolean':
+            return {
+                commentLines,
+                type: 'type-reference',
+                typeName: 'boolean',
+            };
+        case 'integer':
+            return {
+                commentLines,
+                type: 'type-reference',
+                typeName: 'number',
+            };
+        case 'object':
+            return generateObjectType(schema, refMap);
+    }
+}

package/dist/generateUnionType.d.ts

@@ -0,0 +1,3 @@
+import type { JSONSchema4, JSONSchema4Type } from '@typescript-eslint/utils/json-schema';
+import type { RefMap, UnionAST } from './types.js';
+export declare function generateUnionType(members: (JSONSchema4 | JSONSchema4Type)[], refMap: RefMap): UnionAST;

package/dist/generateUnionType.js

@@ -0,0 +1,37 @@
+import { NotSupportedError } from './errors.js';
+import { generateType } from './generateType.js';
+export function generateUnionType(members, refMap) {
+    const elements = [];
+    for (const memberSchema of members) {
+        elements.push((() => {
+            switch (typeof memberSchema) {
+                case 'string':
+                    return {
+                        code: `'${memberSchema.replaceAll("'", "\\'")}'`,
+                        commentLines: [],
+                        type: 'literal',
+                    };
+                case 'number':
+                case 'boolean':
+                    return {
+                        code: `${memberSchema}`,
+                        commentLines: [],
+                        type: 'literal',
+                    };
+                case 'object':
+                    if (memberSchema == null) {
+                        throw new NotSupportedError('null in an enum', memberSchema);
+                    }
+                    if (Array.isArray(memberSchema)) {
+                        throw new NotSupportedError('array in an enum', memberSchema);
+                    }
+                    return generateType(memberSchema, refMap);
+            }
+        })());
+    }
+    return {
+        commentLines: [],
+        elements,
+        type: 'union',
+    };
+}

package/dist/getCommentLines.d.ts

@@ -0,0 +1,2 @@
+import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema';
+export declare function getCommentLines(schema: JSONSchema4): string[];

package/dist/getCommentLines.js

@@ -0,0 +1,7 @@
+export function getCommentLines(schema) {
+    const lines = [];
+    if (schema.description) {
+        lines.push(schema.description);
+    }
+    return lines;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema';
+/**
+ * Converts rule options schema(s) to the equivalent TypeScript type string.
+ *
+ * @param schema Original rule schema(s) as declared in `meta.schema`.
+ * @returns Stringified TypeScript type(s) equivalent to the options schema(s).
+ */
+export declare function schemaToTypes(schema: JSONSchema4 | readonly JSONSchema4[]): string;

package/dist/index.js

@@ -0,0 +1,59 @@
+import { TSUtils } from '@typescript-eslint/utils';
+import { generateType } from './generateType.js';
+import { optimizeAST } from './optimizeAST.js';
+import { printTypeAlias } from './printAST.js';
+/**
+ * Converts rule options schema(s) to the equivalent TypeScript type string.
+ *
+ * @param schema Original rule schema(s) as declared in `meta.schema`.
+ * @returns Stringified TypeScript type(s) equivalent to the options schema(s).
+ */
+export function schemaToTypes(schema) {
+    const [isArraySchema, schemaNormalized] = TSUtils.isArray(schema)
+        ? [true, schema]
+        : [false, [schema]];
+    if (schemaNormalized.length === 0) {
+        return ['/** No options declared */', 'type Options = [];'].join('\n');
+    }
+    const refTypes = [];
+    const types = [];
+    for (let i = 0; i < schemaNormalized.length; i += 1) {
+        const result = compileSchema(schemaNormalized[i], i);
+        refTypes.push(...result.refTypes);
+        types.push(result.type);
+    }
+    const optionsType = isArraySchema
+        ? printTypeAlias('Options', {
+            commentLines: [],
+            elements: types,
+            spreadType: null,
+            type: 'tuple',
+        })
+        : printTypeAlias('Options', types[0]);
+    return [...refTypes, optionsType].join('\n\n');
+}
+function compileSchema(schema, index) {
+    const refTypes = [];
+    const refMap = new Map();
+    // we only support defs at the top level for simplicity
+    const defs = schema.$defs ?? schema.definitions;
+    if (defs) {
+        for (const [defKey, defSchema] of Object.entries(defs)) {
+            const typeName = toPascalCase(defKey);
+            refMap.set(`#/$defs/${defKey}`, typeName);
+            refMap.set(`#/items/${index}/$defs/${defKey}`, typeName);
+            const type = generateType(defSchema, refMap);
+            optimizeAST(type);
+            refTypes.push(printTypeAlias(typeName, type));
+        }
+    }
+    const type = generateType(schema, refMap);
+    optimizeAST(type);
+    return {
+        refTypes,
+        type,
+    };
+}
+function toPascalCase(key) {
+    return key[0].toUpperCase() + key.substring(1);
+}

package/dist/optimizeAST.d.ts

@@ -0,0 +1,2 @@
+import type { SchemaAST } from './types.js';
+export declare function optimizeAST(ast: SchemaAST | null): void;

package/dist/optimizeAST.js

@@ -0,0 +1,60 @@
+export function optimizeAST(ast) {
+    if (ast == null) {
+        return;
+    }
+    switch (ast.type) {
+        case 'array': {
+            optimizeAST(ast.elementType);
+            return;
+        }
+        case 'literal':
+            return;
+        case 'object': {
+            for (const property of ast.properties) {
+                optimizeAST(property.type);
+            }
+            optimizeAST(ast.indexSignature);
+            return;
+        }
+        case 'tuple': {
+            for (const element of ast.elements) {
+                optimizeAST(element);
+            }
+            optimizeAST(ast.spreadType);
+            return;
+        }
+        case 'type-reference':
+            return;
+        case 'union': {
+            const elements = unwrapUnions(ast);
+            for (const element of elements) {
+                optimizeAST(element);
+            }
+            // hacky way to deduplicate union members
+            const uniqueElementsMap = new Map();
+            for (const element of elements) {
+                uniqueElementsMap.set(JSON.stringify(element), element);
+            }
+            const uniqueElements = [...uniqueElementsMap.values()];
+            // @ts-expect-error -- purposely overwriting the property with a flattened list
+            ast.elements = uniqueElements;
+            return;
+        }
+    }
+}
+function unwrapUnions(union) {
+    const elements = [];
+    for (const element of union.elements) {
+        if (element.type === 'union') {
+            elements.push(...unwrapUnions(element));
+        }
+        else {
+            elements.push(element);
+        }
+    }
+    if (elements.length > 0) {
+        // preserve the union's comment lines by prepending them to the first element's lines
+        elements[0].commentLines.unshift(...union.commentLines);
+    }
+    return elements;
+}

package/dist/printAST.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaAST } from './types.js';
+export declare function printTypeAlias(aliasName: string, ast: SchemaAST): string;
+export declare function printASTWithComment(ast: SchemaAST): string;

package/dist/printAST.js

@@ -0,0 +1,130 @@
+import naturalCompare from 'natural-compare';
+export function printTypeAlias(aliasName, ast) {
+    return `${printComment(ast)}type ${aliasName} = ${printAST(ast).code}`;
+}
+export function printASTWithComment(ast) {
+    const result = printAST(ast);
+    return `${printComment(result)}${result.code}`;
+}
+function printComment({ commentLines: commentLinesIn, }) {
+    if (commentLinesIn == null || commentLinesIn.length === 0) {
+        return '';
+    }
+    const commentLines = [];
+    for (const line of commentLinesIn) {
+        commentLines.push(...line.split('\n'));
+    }
+    if (commentLines.length === 1) {
+        return `/** ${commentLines[0]} */\n`;
+    }
+    return ['/**', ...commentLines.map(l => ` * ${l}`), ' */', ''].join('\n');
+}
+function printAST(ast) {
+    switch (ast.type) {
+        case 'array': {
+            const code = printAndMaybeParenthesise(ast.elementType);
+            return {
+                code: `${code.code}[]`,
+                commentLines: [...ast.commentLines, ...code.commentLines],
+            };
+        }
+        case 'literal':
+            return {
+                code: ast.code,
+                commentLines: ast.commentLines,
+            };
+        case 'object': {
+            const properties = [];
+            // sort the properties so that we get consistent output regardless
+            // of import declaration order
+            const sortedPropertyDefs = ast.properties.sort((a, b) => naturalCompare(a.name, b.name));
+            for (const property of sortedPropertyDefs) {
+                const result = printAST(property.type);
+                properties.push(`${printComment(result)}${property.name}${property.optional ? '?:' : ':'} ${result.code}`);
+            }
+            if (ast.indexSignature) {
+                const result = printAST(ast.indexSignature);
+                properties.push(`${printComment(result)}[k: string]: ${result.code}`);
+            }
+            return {
+                // force insert a newline so prettier consistently prints all objects as multiline
+                code: `{\n${properties.join(';\n')}}`,
+                commentLines: ast.commentLines,
+            };
+        }
+        case 'tuple': {
+            const elements = [];
+            for (const element of ast.elements) {
+                elements.push(printASTWithComment(element));
+            }
+            if (ast.spreadType) {
+                const result = printAndMaybeParenthesise(ast.spreadType);
+                elements.push(`${printComment(result)}...${result.code}[]`);
+            }
+            return {
+                code: `[${elements.join(',')}]`,
+                commentLines: ast.commentLines,
+            };
+        }
+        case 'type-reference':
+            return {
+                code: ast.typeName,
+                commentLines: ast.commentLines,
+            };
+        case 'union':
+            return {
+                code: ast.elements
+                    .map(element => {
+                    const result = printAST(element);
+                    const code = `${printComment(result)} | ${result.code}`;
+                    return {
+                        code,
+                        element,
+                    };
+                })
+                    // sort the union members so that we get consistent output regardless
+                    // of declaration order
+                    .sort((a, b) => compareElements(a, b))
+                    .map(el => el.code)
+                    .join('\n'),
+                commentLines: ast.commentLines,
+            };
+    }
+}
+function compareElements(a, b) {
+    if (a.element.type !== b.element.type) {
+        return naturalCompare(a.code, b.code);
+    }
+    switch (a.element.type) {
+        case 'array':
+        case 'literal':
+        case 'type-reference':
+        case 'object':
+        case 'union':
+            return naturalCompare(a.code, b.code);
+        case 'tuple': {
+            // natural compare will sort longer tuples before shorter ones
+            // which is the opposite of what we want, so we sort first by length THEN
+            // by code to ensure shorter tuples come first
+            const aElement = a.element;
+            const bElement = b.element;
+            if (aElement.elements.length !== bElement.elements.length) {
+                return aElement.elements.length - bElement.elements.length;
+            }
+            return naturalCompare(a.code, b.code);
+        }
+    }
+}
+function printAndMaybeParenthesise(ast) {
+    const printed = printAST(ast);
+    if (ast.type === 'union') {
+        return {
+            code: `(${printed.code})`,
+            commentLines: printed.commentLines,
+        };
+    }
+    return {
+        code: printed.code,
+        commentLines: printed.commentLines,
+    };
+}