feat: Under-specified objects are Record<string, unknown>

Author: duncanbeevers

README.md

@@ -149,6 +149,7 @@ The following flags can be appended to the CLI command.
 | `--http-method`                | `-m`  | `GET`    | Provide the HTTP Verb/Method for fetching a schema from a remote URL                                                         |
 | `--immutable-types`            |       | `false`  | Generates immutable types (readonly properties and readonly array)                                                           |
 | `--additional-properties`      |       | `false`  | Allow arbitrary properties for all schema objects without `additionalProperties: false`                                      |
+| `--empty-objects-unknown`      |       | `false`  | Allow arbitrary properties for schema objects with no specified properties, and no specified `additionalProperties`          |
 | `--default-non-nullable`       |       | `false`  | Treat schema objects with default values as non-nullable                                                                     |
 | `--export-type`                | `-t`  | `false`  | Export `type` instead of `interface`                                                                                         |
 | `--path-params-as-types`       |       | `false`  | Allow dynamic string lookups on the `paths` object                                                                           |

bin/cli.js

@@ -22,6 +22,7 @@ Options
   --export-type, -t            (optional) Export "type" instead of "interface"
   --immutable-types            (optional) Generates immutable types (readonly properties and readonly array)
   --additional-properties      (optional) Allow arbitrary properties for all schema objects without "additionalProperties: false"
+  --empty-objects-unknown      (optional) Allow arbitrary properties for schema objects with no specified properties, and no specified "additionalProperties"
   --default-non-nullable       (optional) If a schema object has a default value set, don’t mark it as nullable
   --support-array-length       (optional) Generate tuples using array minItems / maxItems
   --path-params-as-types       (optional) Substitute path parameter names with their respective types

src/index.ts

@@ -46,6 +46,7 @@ async function openapiTS(
     transform: options && typeof options.transform === "function" ? options.transform : undefined,
     postTransform: options && typeof options.postTransform === "function" ? options.postTransform : undefined,
     immutableTypes: options.immutableTypes || false,
+    emptyObjectsUnknown: options.emptyObjectsUnknown || false,
     indentLv: 0,
     operations: {},
     pathParamsAsTypes: options.pathParamsAsTypes || false,

src/transform/schema-object.ts

@@ -255,5 +255,8 @@ export function defaultSchemaObjectTransform(
   // nullable (3.0)
   if (schemaObject.nullable) finalType = tsUnionOf(finalType || "Record<string, unknown>", "null");
 
-  return finalType || "Record<string, never>"; // if no type could be generated, fall back to “empty object” type
+  if (finalType) return finalType;
+
+  // if no type could be generated, fall back to “empty object” type
+  return ctx.emptyObjectsUnknown ? "Record<string, unknown>" : "Record<string, never>";
 }

src/types.ts

@@ -567,6 +567,8 @@ export interface OpenAPITSOptions {
   alphabetize?: boolean;
   /** Specify auth if using openapi-typescript to fetch URL */
   auth?: string;
+  /** Allow schema objects with no specified properties to have additional properties if not expressly forbidden? (default: false) */
+  emptyObjectsUnknown?: boolean;
   /** Specify current working directory (cwd) to resolve remote schemas on disk (not needed for remote URL schemas) */
   cwd?: URL;
   /** Should schema objects with a default value not be considered optional? */
@@ -632,6 +634,7 @@ export type Subschema =
 export interface GlobalContext {
   additionalProperties: boolean;
   alphabetize: boolean;
+  emptyObjectsUnknown: boolean;
   defaultNonNullable: boolean;
   discriminators: { [$ref: string]: DiscriminatorObject };
   transform: OpenAPITSOptions["transform"];

test/components-object.test.ts

@@ -4,6 +4,7 @@ import transformComponentsObject from "../src/transform/components-object.js";
 const options: GlobalContext = {
   additionalProperties: false,
   alphabetize: false,
+  emptyObjectsUnknown: false,
   defaultNonNullable: false,
   discriminators: {},
   immutableTypes: false,

test/header-object.test.ts

@@ -6,6 +6,7 @@ const options: TransformHeaderObjectOptions = {
   ctx: {
     additionalProperties: false,
     alphabetize: false,
+    emptyObjectsUnknown: false,
     defaultNonNullable: false,
     discriminators: {},
     immutableTypes: false,

test/load.test.ts

@@ -105,6 +105,7 @@ async function load(
     urlCache: new Set(),
     fetch: vi.fn(unidiciFetch),
     additionalProperties: false,
+    emptyObjectsUnknown: false,
     alphabetize: false,
     defaultNonNullable: false,
     discriminators: {},

test/path-item-object.test.ts

@@ -6,6 +6,7 @@ const options: TransformPathItemObjectOptions = {
   ctx: {
     additionalProperties: false,
     alphabetize: false,
+    emptyObjectsUnknown: false,
     defaultNonNullable: false,
     discriminators: {},
     immutableTypes: false,

test/paths-object.test.ts

@@ -4,6 +4,7 @@ import transformPathsObject from "../src/transform/paths-object.js";
 const options: GlobalContext = {
   additionalProperties: false,
   alphabetize: false,
+  emptyObjectsUnknown: false,
   defaultNonNullable: false,
   discriminators: {},
   immutableTypes: false,

test/request-body-object.test.ts

@@ -6,6 +6,7 @@ const options: TransformRequestBodyObjectOptions = {
   ctx: {
     additionalProperties: false,
     alphabetize: false,
+    emptyObjectsUnknown: false,
     defaultNonNullable: false,
     discriminators: {},
     immutableTypes: false,

test/schema-object.test.ts

@@ -6,6 +6,7 @@ const options: TransformSchemaObjectOptions = {
   ctx: {
     additionalProperties: false,
     alphabetize: false,
+    emptyObjectsUnknown: false,
     defaultNonNullable: false,
     discriminators: {},
     immutableTypes: false,
@@ -121,6 +122,25 @@ describe("Schema Object", () => {
     });
 
     describe("object", () => {
+      test("empty", () => {
+        const schema: SchemaObject = {
+          type: "object",
+        };
+        const generated = transformSchemaObject(schema, options);
+        expect(generated).toBe(`Record<string, never>`);
+      });
+
+      test("empty with emptyObjectsUnknown", () => {
+        const schema: SchemaObject = {
+          type: "object",
+        };
+        const generated = transformSchemaObject(schema, {
+          ...options,
+          ctx: { ...options.ctx, emptyObjectsUnknown: true },
+        });
+        expect(generated).toBe(`Record<string, unknown>`);
+      });
+
       test("basic", () => {
         const schema: SchemaObject = {
           type: "object",
@@ -361,6 +381,30 @@ describe("Schema Object", () => {
       });
     });
 
+    describe("emptyObjectsUnknown", () => {
+      describe("with object with no specified properties", () => {
+        const schema: SchemaObject = {
+          type: "object",
+        };
+
+        test("true", () => {
+          const generated = transformSchemaObject(schema, {
+            ...options,
+            ctx: { ...options.ctx, emptyObjectsUnknown: true },
+          });
+          expect(generated).toBe(`Record<string, unknown>`);
+        });
+
+        test("false", () => {
+          const generated = transformSchemaObject(schema, {
+            ...options,
+            ctx: { ...options.ctx, emptyObjectsUnknown: false },
+          });
+          expect(generated).toBe(`Record<string, never>`);
+        });
+      });
+    });
+
     describe("defaultNonNullable", () => {
       test("true", () => {
         const schema: SchemaObject = {