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

package/src/generateType.ts

@@ -0,0 +1,126 @@
+import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema';
+
+import { TSUtils } from '@typescript-eslint/utils';
+
+import type { SchemaAST, RefMap } from './types.js';
+
+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: JSONSchema4, refMap: RefMap): SchemaAST {
+  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/src/generateUnionType.ts

@@ -0,0 +1,54 @@
+import type {
+  JSONSchema4,
+  JSONSchema4Type,
+} from '@typescript-eslint/utils/json-schema';
+
+import type { SchemaAST, RefMap, UnionAST } from './types.js';
+
+import { NotSupportedError } from './errors.js';
+import { generateType } from './generateType.js';
+
+export function generateUnionType(
+  members: (JSONSchema4 | JSONSchema4Type)[],
+  refMap: RefMap,
+): UnionAST {
+  const elements: SchemaAST[] = [];
+
+  for (const memberSchema of members) {
+    elements.push(
+      ((): SchemaAST => {
+        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/src/getCommentLines.ts

@@ -0,0 +1,9 @@
+import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema';
+
+export function getCommentLines(schema: JSONSchema4): string[] {
+  const lines: string[] = [];
+  if (schema.description) {
+    lines.push(schema.description);
+  }
+  return lines;
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema';
+
+import { TSUtils } from '@typescript-eslint/utils';
+
+import type { SchemaAST } from './types.js';
+
+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: JSONSchema4 | readonly JSONSchema4[],
+): string {
+  const [isArraySchema, schemaNormalized] = TSUtils.isArray(schema)
+    ? [true, schema]
+    : [false, [schema]];
+
+  if (schemaNormalized.length === 0) {
+    return ['/** No options declared */', 'type Options = [];'].join('\n');
+  }
+
+  const refTypes: string[] = [];
+  const types: SchemaAST[] = [];
+  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: JSONSchema4,
+  index: number,
+): { refTypes: string[]; type: SchemaAST } {
+  const refTypes: string[] = [];
+
+  const refMap = new Map<string, string>();
+  // 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: string): string {
+  return key[0].toUpperCase() + key.substring(1);
+}

package/src/optimizeAST.ts

@@ -0,0 +1,72 @@
+import type { SchemaAST, UnionAST } from './types.js';
+
+export function optimizeAST(ast: SchemaAST | null): void {
+  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<string, SchemaAST>();
+      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: UnionAST): SchemaAST[] {
+  const elements: SchemaAST[] = [];
+  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/src/printAST.ts

@@ -0,0 +1,168 @@
+import naturalCompare from 'natural-compare';
+
+import type { SchemaAST, TupleAST } from './types.js';
+
+export function printTypeAlias(aliasName: string, ast: SchemaAST): string {
+  return `${printComment(ast)}type ${aliasName} = ${printAST(ast).code}`;
+}
+
+export function printASTWithComment(ast: SchemaAST): string {
+  const result = printAST(ast);
+  return `${printComment(result)}${result.code}`;
+}
+
+function printComment({
+  commentLines: commentLinesIn,
+}: {
+  readonly commentLines?: string[] | null | undefined;
+}): string {
+  if (commentLinesIn == null || commentLinesIn.length === 0) {
+    return '';
+  }
+
+  const commentLines: string[] = [];
+  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');
+}
+
+interface CodeWithComments {
+  code: string;
+  commentLines: string[];
+}
+function printAST(ast: SchemaAST): CodeWithComments {
+  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,
+      };
+  }
+}
+
+interface Element {
+  code: string;
+  element: SchemaAST;
+}
+function compareElements(a: Element, b: Element): number {
+  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 as TupleAST;
+      if (aElement.elements.length !== bElement.elements.length) {
+        return aElement.elements.length - bElement.elements.length;
+      }
+      return naturalCompare(a.code, b.code);
+    }
+  }
+}
+
+function printAndMaybeParenthesise(ast: SchemaAST): CodeWithComments {
+  const printed = printAST(ast);
+  if (ast.type === 'union') {
+    return {
+      code: `(${printed.code})`,
+      commentLines: printed.commentLines,
+    };
+  }
+  return {
+    code: printed.code,
+    commentLines: printed.commentLines,
+  };
+}

package/src/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Maps ref paths to generated type names.
+ */
+export type RefMap = ReadonlyMap<
+  // ref path
+  string,
+  // type name
+  string
+>;
+
+/**
+ * Minimal representation of the nodes in a schema being compiled to types.
+ */
+export type SchemaAST =
+  | ArrayAST
+  | LiteralAST
+  | ObjectAST
+  | TupleAST
+  | TypeReferenceAST
+  | UnionAST;
+
+export interface BaseSchemaASTNode {
+  readonly commentLines: string[];
+}
+
+export interface ArrayAST extends BaseSchemaASTNode {
+  readonly elementType: SchemaAST;
+  readonly type: 'array';
+}
+export interface LiteralAST extends BaseSchemaASTNode {
+  readonly code: string;
+  readonly type: 'literal';
+}
+export interface ObjectAST extends BaseSchemaASTNode {
+  readonly indexSignature: SchemaAST | null;
+  readonly properties: {
+    readonly name: string;
+    readonly optional: boolean;
+    readonly type: SchemaAST;
+  }[];
+  readonly type: 'object';
+}
+export interface TupleAST extends BaseSchemaASTNode {
+  readonly elements: SchemaAST[];
+  readonly spreadType: SchemaAST | null;
+  readonly type: 'tuple';
+}
+export interface TypeReferenceAST extends BaseSchemaASTNode {
+  readonly type: 'type-reference';
+  readonly typeName: string;
+}
+export interface UnionAST extends BaseSchemaASTNode {
+  readonly elements: SchemaAST[];
+  readonly type: 'union';
+}

package/tests/index.test.ts

@@ -0,0 +1,148 @@
+import { schemaToTypes } from '../src/index.js';
+
+describe(schemaToTypes, () => {
+  it('returns a [] type when the schema is an empty array', () => {
+    const actual = schemaToTypes([]);
+
+    expect(actual).toMatchInlineSnapshot(`
+      "/** No options declared */
+      type Options = [];"
+    `);
+  });
+
+  it('returns a single Options type when the schema is not an array', () => {
+    const actual = schemaToTypes({ type: 'string' });
+
+    expect(actual).toMatchInlineSnapshot(`"type Options = string"`);
+  });
+
+  it('returns an array Options type when the schema is an array', () => {
+    const actual = schemaToTypes([{ type: 'string' }]);
+
+    expect(actual).toMatchInlineSnapshot(`"type Options = [string]"`);
+  });
+
+  it('returns a complex Options type when the schema contains an array of items', () => {
+    const actual = schemaToTypes([
+      {
+        items: [{ type: 'string' }],
+        type: 'array',
+      },
+    ]);
+
+    expect(actual).toMatchInlineSnapshot(`
+      "type Options = [ | []
+ | [string]]"
+    `);
+  });
+
+  it('returns a complex Options type when the schema is nested', () => {
+    const actual = schemaToTypes([
+      {
+        description: 'My schema items.',
+        items: { type: 'string' },
+        type: 'array',
+      },
+    ]);
+
+    expect(actual).toMatchInlineSnapshot(`
+      "type Options = [/** My schema items. */
+      string[]]"
+    `);
+  });
+
+  it('factors in one $ref property when a $defs property exists at the top level', () => {
+    const actual = schemaToTypes([
+      {
+        $defs: {
+          defOption: {
+            enum: ['a', 'b'],
+            type: 'string',
+          },
+        },
+        additionalProperties: false,
+        properties: {
+          one: {
+            $ref: '#/items/0/$defs/defOption',
+          },
+        },
+        type: 'object',
+      },
+    ]);
+
+    expect(actual).toMatchInlineSnapshot(`
+      "type DefOption =  | 'a'
+       | 'b'
+
+      type Options = [{
+      one?: DefOption}]"
+    `);
+  });
+
+  it('factors in one $ref property when a definitions property exists at the top level', () => {
+    const actual = schemaToTypes([
+      {
+        additionalProperties: false,
+        definitions: {
+          defOption: {
+            enum: ['a', 'b'],
+            type: 'string',
+          },
+        },
+        properties: {
+          one: {
+            $ref: '#/items/0/$defs/defOption',
+          },
+        },
+        type: 'object',
+      },
+    ]);
+
+    expect(actual).toMatchInlineSnapshot(`
+      "type DefOption =  | 'a'
+       | 'b'
+
+      type Options = [{
+      one?: DefOption}]"
+    `);
+  });
+
+  it('factors in two $ref properties when two $defs properties exist at the top level', () => {
+    const actual = schemaToTypes([
+      {
+        $defs: {
+          defOptionOne: {
+            enum: ['a', 'b'],
+            type: 'string',
+          },
+          defOptionTwo: {
+            enum: ['c', 'd'],
+            type: 'string',
+          },
+        },
+        additionalProperties: false,
+        properties: {
+          one: {
+            $ref: '#/items/0/$defs/defOptionOne',
+          },
+          two: {
+            $ref: '#/items/0/$defs/defOptionTwo',
+          },
+        },
+        type: 'object',
+      },
+    ]);
+
+    expect(actual).toMatchInlineSnapshot(`
+      "type DefOptionOne =  | 'a'
+       | 'b'
+
+      type DefOptionTwo =  | 'c'
+       | 'd'
+
+      type Options = [{
+      one?: DefOptionOne;
+      two?: DefOptionTwo}]"
+    `);
+  });
+});