@appweaver/client 1.2.1 → 1.3.1

package/cjs/utils/hoist-util.js

@@ -0,0 +1,338 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hoistSharedTypes = hoistSharedTypes;
+const constants_1 = require("../constants");
+/** Keys documenting a schema node rather than describing its structure. They are kept on the
+ * property the node is hoisted out of, so no property loses its description along the way. */
+const ANNOTATION_KEYS = ['description', 'example', 'examples', 'deprecated'];
+/**
+ * Hoists the schemas an OpenAPI document repeats inline across its definitions into shared
+ * definitions of their own, replacing every occurrence with a reference to the hoisted
+ * definition.
+ *
+ * An Appweaver schema declares the same shapes over and over, once per property that accepts
+ * them, and each of them would otherwise be spelled out again in the generated types (i.e. the
+ * `asc | desc` enum of every sortable field, or the accepted value of every filterable field of
+ * every resource). Two kinds of schema are hoisted:
+ *
+ * - The well known shapes of {@link SHARED_SCHEMA_SHAPES}, matched in the order they are
+ *   declared so an outer shape is hoisted before the shapes nested inside it.
+ * - The enums the definitions repeat, named after {@link SHARED_ENUM_NAMES} when their values
+ *   are well known, and otherwise after the part the declaring definitions have in common
+ *   followed by the property name (i.e. `PostCreate` and `PostSingle` declaring `status` give
+ *   `PostStatus`). Enums whose name cannot be resolved are left inline.
+ *
+ * Only the structure of a schema decides whether it is hoisted, and every occurrence keeps the
+ * documentation it carries, so no property loses its description or example along the way.
+ *
+ * A schema declared only once, or whose name is already taken, is left inline as well.
+ *
+ * The given schema is mutated in place.
+ *
+ * @param {OpenAPI3} schema The OpenAPI v3 schema to hoist the shared definitions of.
+ * @return {string[]} The names of the hoisted definitions, in the order they were created.
+ */
+function hoistSharedTypes(schema) {
+    const definitions = schema.components?.schemas;
+    if (!definitions) {
+        return [];
+    }
+    const takenNames = new Set(Object.keys(definitions));
+    for (const definition of Object.values(definitions)) {
+        const title = definition?.['title'];
+        if (typeof title === 'string') {
+            takenNames.add(title);
+        }
+    }
+    const hoistedNames = [];
+    for (const { name, schema: shape } of constants_1.SHARED_SCHEMA_SHAPES) {
+        if (hoistShape(definitions, name, shape, takenNames)) {
+            hoistedNames.push(name);
+        }
+    }
+    hoistedNames.push(...hoistEnums(definitions, takenNames));
+    return hoistedNames;
+}
+/**
+ * Hoists every occurrence of a well known shape into a definition of the given name. The
+ * definition is built from the first occurrence, so it holds the references the shape declares
+ * by title as the references of the document.
+ *
+ * @param {Record<string, unknown>} definitions The definitions of the schema.
+ * @param {string} name The name of the definition the shape is hoisted into.
+ * @param {unknown} shape The shape to hoist, holding its references as definition titles.
+ * @param {Set<string>} takenNames The definition names already in use.
+ * @return {boolean} Whether the shape was hoisted.
+ */
+function hoistShape(definitions, name, shape, takenNames) {
+    const titles = definitionTitles(definitions);
+    const signature = schemaSignature(shape, titles);
+    const groups = collectOccurrences(definitions, (node) => schemaSignature(structure(node), titles) === signature ? name : undefined);
+    const occurrences = groups.get(name);
+    if (!occurrences || occurrences.length < 2 || takenNames.has(name)) {
+        return false;
+    }
+    takenNames.add(name);
+    const { container, key } = occurrences[0];
+    definitions[name] = {
+        title: name,
+        ...structure(container[key])
+    };
+    for (const occurrence of occurrences) {
+        replaceWithReference(occurrence, name);
+    }
+    return true;
+}
+/**
+ * Hoists the enums the definitions repeat into shared definitions named after their values.
+ *
+ * @param {Record<string, unknown>} definitions The definitions of the schema.
+ * @param {Set<string>} takenNames The definition names already in use.
+ * @return {string[]} The names of the hoisted definitions, in the order they were created.
+ */
+function hoistEnums(definitions, takenNames) {
+    // Enums declared by identical schema content, keyed by that content. The
+    // documentation of a node is left out of the key, since every occurrence keeps
+    // the documentation of its own when it is replaced by a reference
+    const groups = collectOccurrences(definitions, (node) => Array.isArray(node['enum']) ? stableStringify(structure(node)) : undefined);
+    const hoistedNames = [];
+    for (const [content, occurrences] of groups) {
+        if (occurrences.length < 2) {
+            continue;
+        }
+        const name = resolveEnumName(JSON.parse(content), occurrences);
+        if (!name || takenNames.has(name)) {
+            continue;
+        }
+        takenNames.add(name);
+        hoistedNames.push(name);
+        definitions[name] = { title: name, ...JSON.parse(content) };
+        for (const occurrence of occurrences) {
+            replaceWithReference(occurrence, name);
+        }
+    }
+    return hoistedNames;
+}
+/**
+ * Replaces the schema node of an occurrence with a reference to the given definition, keeping
+ * the documentation the node carries.
+ *
+ * @param {Occurrence} occurrence The occurrence to replace.
+ * @param {string} name The name of the definition to reference.
+ */
+function replaceWithReference({ container, key }, name) {
+    const node = container[key];
+    container[key] = {
+        ...annotations(node),
+        $ref: `#/components/schemas/${name}`
+    };
+}
+/**
+ * Collects every inline schema the matcher accepts into a map of occurrences, grouped by the
+ * key the matcher returns for them. A node the matcher accepts is not descended into, so an
+ * outer match wins over the nodes nested inside it.
+ *
+ * @param {Record<string, unknown>} definitions The definitions of the schema.
+ * @param {Matcher} match The matcher deciding which nodes are collected.
+ * @return {Map<string, Occurrence[]>} The collected occurrences, grouped by matcher key.
+ */
+function collectOccurrences(definitions, match) {
+    const groups = new Map();
+    for (const [key, definition] of Object.entries(definitions)) {
+        if (definition && typeof definition === 'object') {
+            const owner = definition['title'];
+            collect(definition, typeof owner === 'string' ? owner : key, '', match, groups);
+        }
+    }
+    return groups;
+}
+/**
+ * Collects every inline schema declared below the given schema node into the groups map.
+ *
+ * @param {SchemaContainer} container The schema node to collect the schemas of.
+ * @param {string} owner The name of the definition the node belongs to.
+ * @param {string} property The name of the property the node is declared under, if any.
+ * @param {Matcher} match The matcher deciding which nodes are collected.
+ * @param {Map<string, Occurrence[]>} groups The collected occurrences, grouped by matcher key.
+ */
+function collect(container, owner, property, match, groups) {
+    const entries = Array.isArray(container)
+        ? container.map((value, index) => [index, value])
+        : Object.entries(container);
+    for (const [key, value] of entries) {
+        if (!value || typeof value !== 'object') {
+            continue;
+        }
+        // The keys of a `properties` object name the schemas below them, everything
+        // else keeps the property name of the node it was reached through
+        if (key === 'properties' && !Array.isArray(value)) {
+            const properties = value;
+            for (const name of Object.keys(properties)) {
+                visit(properties, name, owner, name, match, groups);
+            }
+            continue;
+        }
+        visit(container, key, owner, property, match, groups);
+    }
+}
+/**
+ * Records the schema held by the container under the given key as an occurrence, or descends
+ * into it when the matcher does not accept it.
+ *
+ * @param {SchemaContainer} container The container holding the schema node.
+ * @param {string | number} key The key the schema node is held under.
+ * @param {string} owner The name of the definition the node belongs to.
+ * @param {string} property The name of the property the node is declared under, if any.
+ * @param {Matcher} match The matcher deciding which nodes are collected.
+ * @param {Map<string, Occurrence[]>} groups The collected occurrences, grouped by matcher key.
+ */
+function visit(container, key, owner, property, match, groups) {
+    const node = container[key];
+    const group = match(node);
+    if (group !== undefined) {
+        const occurrences = groups.get(group) ?? [];
+        occurrences.push({ container, key, owner, property });
+        groups.set(group, occurrences);
+        return;
+    }
+    collect(node, owner, property, match, groups);
+}
+/**
+ * Resolves the name of the definition an enum is hoisted into, preferring the name given to
+ * its values by {@link SHARED_ENUM_NAMES} and falling back to the common part of the names of
+ * the definitions declaring it, followed by the property name they all declare it under.
+ *
+ * @param {SchemaNode} node The enum schema to resolve the name of.
+ * @param {Occurrence[]} occurrences The places the enum is declared in.
+ * @return {string | undefined} The resolved name, or undefined when the enum has no name to
+ * be hoisted under.
+ */
+function resolveEnumName(node, occurrences) {
+    const values = node['enum'];
+    const knownName = constants_1.SHARED_ENUM_NAMES[values.join('|')];
+    if (knownName) {
+        return knownName;
+    }
+    const { property } = occurrences[0];
+    if (!property || occurrences.some((o) => o.property !== property)) {
+        return undefined;
+    }
+    const prefix = commonNamePrefix(occurrences.map((o) => o.owner));
+    if (!prefix) {
+        return undefined;
+    }
+    return prefix + property.charAt(0).toUpperCase() + property.slice(1);
+}
+/**
+ * Resolves the longest prefix the given names share, cut at a word boundary so the result
+ * stays a readable name (i.e. `HealthCheckResponse` and `HealthCheckResult` give
+ * `HealthCheck` rather than `HealthCheckRes`).
+ *
+ * @param {string[]} names The names to find the common prefix of.
+ * @return {string} The common prefix, empty when the names start with different words.
+ */
+function commonNamePrefix(names) {
+    const wordsPerName = names.map((name) => name.match(/[A-Z]+(?![a-z])|[A-Z]?[a-z0-9]+|[A-Z]/g) ?? []);
+    const words = [];
+    for (let i = 0; i < wordsPerName[0].length; i++) {
+        const word = wordsPerName[0][i];
+        if (wordsPerName.some((other) => other[i] !== word)) {
+            break;
+        }
+        words.push(word);
+    }
+    return words.join('');
+}
+/**
+ * Maps every definition key to the title it is generated under, so a reference can be compared
+ * by the name it resolves to rather than by the generated key holding it.
+ *
+ * @param {Record<string, unknown>} definitions The definitions of the schema.
+ * @return {Map<string, string>} The title of every definition, keyed by its definition key.
+ */
+function definitionTitles(definitions) {
+    const titles = new Map();
+    for (const [key, definition] of Object.entries(definitions)) {
+        const title = definition?.['title'];
+        titles.set(key, typeof title === 'string' ? title : key);
+    }
+    return titles;
+}
+/**
+ * Returns the documentation keys of a schema node, which the node keeps when it is replaced by
+ * a reference to a hoisted definition.
+ *
+ * @param {SchemaNode} node The schema node to take the documentation of.
+ * @return {SchemaNode} The documentation keys of the node.
+ */
+function annotations(node) {
+    return Object.fromEntries(Object.entries(node).filter(([key]) => ANNOTATION_KEYS.includes(key)));
+}
+/**
+ * Returns the structural keys of a schema node, so two nodes describing the same shape under a
+ * different description compare alike.
+ *
+ * @param {SchemaNode} node The schema node to take the structure of.
+ * @return {SchemaNode} The structural keys of the node.
+ */
+function structure(node) {
+    return Object.fromEntries(Object.entries(node).filter(([key]) => !ANNOTATION_KEYS.includes(key)));
+}
+/**
+ * Serializes a schema with its references resolved to the title of the definition they point
+ * to, so a shape declared by {@link SHARED_SCHEMA_SHAPES} compares equal to the same shape of a
+ * document, whose references name the generated definition keys instead.
+ *
+ * @param {unknown} value The schema to serialize.
+ * @param {Map<string, string>} titles The title of every definition, keyed by definition key.
+ * @return {string} The stable serialization of the schema.
+ */
+function schemaSignature(value, titles) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => schemaSignature(item, titles)).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const entries = Object.keys(value)
+            .sort()
+            .map((key) => {
+            const nested = value[key];
+            const resolved = key === '$ref' && typeof nested === 'string'
+                ? JSON.stringify(referenceTitle(nested, titles))
+                : schemaSignature(nested, titles);
+            return `${JSON.stringify(key)}:${resolved}`;
+        });
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/**
+ * Resolves a reference to the title of the definition it points to.
+ *
+ * @param {string} reference The reference to resolve (i.e. `#/components/schemas/def-1`).
+ * @param {Map<string, string>} titles The title of every definition, keyed by definition key.
+ * @return {string} The title of the referenced definition, or the reference when it points
+ * outside of the definitions of the document.
+ */
+function referenceTitle(reference, titles) {
+    const key = reference.replace('#/components/schemas/', '');
+    return titles.get(key) ?? reference;
+}
+/**
+ * Serializes a value with its object keys sorted, so two schemas holding the same content
+ * in a different key order serialize alike.
+ *
+ * @param {unknown} value The value to serialize.
+ * @return {string} The stable JSON serialization of the value.
+ */
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const entries = Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}

package/cjs/utils/index.d.ts

@@ -1,2 +1,3 @@
 export * from './enum-util';
+export * from './hoist-util';
 export * from './schema-util';

package/cjs/utils/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./enum-util"), exports);
+__exportStar(require("./hoist-util"), exports);
 __exportStar(require("./schema-util"), exports);

package/esm/commands/generate-command.js

@@ -33,7 +33,9 @@ export function generateCommand(program) {
         const schemaContent = await readSchemaContent(schemaPath);
         const schemaObject = await toSchemaObject(schemaContent);
         if (!clientOnly && !noTypes) {
-            const typesContent = await generateTypes(schemaObject);
+            const typesContent = await generateTypes(schemaObject, {
+                declaration: typesPath.endsWith('.d.ts')
+            });
             await formatAndWriteFile(typesPath, typesContent, typesOnly || typesPath !== clientPath);
             console.log(`Generated types to ${path.relative(cwd, typesPath)}`);
         }

package/esm/constants.d.ts

@@ -8,6 +8,15 @@ export declare const CONFIG_RESOURCE_FIELD = "x-appweaver-resource";
  * The key is the enum values joined by a `|`; the value is the name of the shared type generated
  * for them. Enums that are not listed here are named after the definitions declaring them. */
 export declare const SHARED_ENUM_NAMES: Record<string, string>;
+/** Shapes an Appweaver schema repeats inline across its definitions, and the name of the shared
+ * definition each of them is hoisted into. A `$ref` names the title of the definition it points
+ * to, since the keys the definitions are generated under vary per document. The shapes are
+ * matched in the order they are declared, so an outer shape is hoisted before the shapes nested
+ * inside it (i.e. `QueryFilterValue` before the `QueryFilterScalar` it is built from). */
+export declare const SHARED_SCHEMA_SHAPES: {
+    name: string;
+    schema: unknown;
+}[];
 /** Suffix used when generating the TypeScript module type name for a resource. */
 export declare const RESOURCE_MODULE_TYPE = "ResourceModuleType";
 /** Maps CRUD operation names to HTTP methods used for matching OpenAPI paths to `ResourceClient` methods. */

package/esm/constants.js

@@ -13,6 +13,33 @@ export const CONFIG_RESOURCE_FIELD = 'x-appweaver-resource';
 export const SHARED_ENUM_NAMES = {
     'asc|desc': 'SortDirection'
 };
+/** The primitive types a plain filter value takes, as an Appweaver schema declares them. */
+const FILTER_SCALAR = {
+    anyOf: [
+        { type: 'string' },
+        { type: 'number' },
+        { type: 'boolean' },
+        { type: 'null' }
+    ]
+};
+/** Shapes an Appweaver schema repeats inline across its definitions, and the name of the shared
+ * definition each of them is hoisted into. A `$ref` names the title of the definition it points
+ * to, since the keys the definitions are generated under vary per document. The shapes are
+ * matched in the order they are declared, so an outer shape is hoisted before the shapes nested
+ * inside it (i.e. `QueryFilterValue` before the `QueryFilterScalar` it is built from). */
+export const SHARED_SCHEMA_SHAPES = [
+    {
+        name: 'QueryFilterValue',
+        schema: {
+            anyOf: [
+                FILTER_SCALAR,
+                { type: 'array', items: FILTER_SCALAR },
+                { $ref: 'QueryCondition' }
+            ]
+        }
+    },
+    { name: 'QueryFilterScalar', schema: FILTER_SCALAR }
+];
 /** Suffix used when generating the TypeScript module type name for a resource. */
 export const RESOURCE_MODULE_TYPE = 'ResourceModuleType';
 /** Maps CRUD operation names to HTTP methods used for matching OpenAPI paths to `ResourceClient` methods. */

package/esm/generators/generate-types.d.ts

@@ -1,9 +1,11 @@
 import { OpenAPI3 } from 'openapi-typescript';
+import { GenerateTypesOptions } from '../types/index.js';
 /**
  * Generates TypeScript types based on an OpenAPI V3 schema content.
  *
  * @param {string | OpenAPI3} schema - The OpenAPI V3 schema to generate types from. The value can be a string
  * representing JSON or YAML format, or an already parsed OpenAPI3 object.
+ * @param {GenerateTypesOptions} [options] - Options controlling how the types are emitted.
  * @return {Promise<string>} A promise that resolves to a string containing the generated TypeScript types.
  */
-export declare function generateTypes(schema: string | OpenAPI3): Promise<string>;
+export declare function generateTypes(schema: string | OpenAPI3, options?: GenerateTypesOptions): Promise<string>;

package/esm/generators/generate-types.js

@@ -1,21 +1,22 @@
 import openapiTS, { astToString } from 'openapi-typescript';
 import ts from 'typescript';
-import { hoistSharedEnums, toSchemaObject } from '../utils/index.js';
+import { hoistSharedTypes, rewriteEnumsAsObjects, toSchemaObject } from '../utils/index.js';
 import { ACCOUNT_MODULE_TYPE, ACCOUNT_TYPES, AUTH_MODULE_TYPE, AUTH_TYPES, CONFIG_FIELD, HEALTH_MODULE_TYPE, HEALTH_TYPES, RESOURCE_MODULE_TYPE, RESOURCE_TYPES } from '../constants.js';
 /**
  * Generates TypeScript types based on an OpenAPI V3 schema content.
  *
  * @param {string | OpenAPI3} schema - The OpenAPI V3 schema to generate types from. The value can be a string
  * representing JSON or YAML format, or an already parsed OpenAPI3 object.
+ * @param {GenerateTypesOptions} [options] - Options controlling how the types are emitted.
  * @return {Promise<string>} A promise that resolves to a string containing the generated TypeScript types.
  */
-export async function generateTypes(schema) {
-    // The schema is copied before the shared enums are hoisted into it, so the
-    // caller keeps the schema it passed in unchanged
+export async function generateTypes(schema, options = {}) {
+    // The schema is copied before the shared definitions are hoisted into it, so
+    // the caller keeps the schema it passed in unchanged
     const schemaObject = typeof schema === 'string'
         ? await toSchemaObject(schema)
         : structuredClone(schema);
-    const sharedEnums = hoistSharedEnums(schemaObject);
+    const sharedTypes = hoistSharedTypes(schemaObject);
     const ast = await openapiTS(schemaObject, {
         exportType: true,
         emptyObjectsUnknown: true,
@@ -52,10 +53,11 @@ export async function generateTypes(schema) {
         }
     });
     let typesContent = astToString(deduplicateUnionConstituents(ast));
-    typesContent = extractSchemaTypes(typesContent, sharedEnums);
+    typesContent = extractSchemaTypes(typesContent, sharedTypes);
     typesContent = combineModuleTypes(typesContent, schemaObject);
     typesContent = deduplicateExportedTypes(typesContent);
-    return replaceFileUploadTypes(typesContent);
+    typesContent = replaceFileUploadTypes(typesContent);
+    return rewriteEnumsAsObjects(typesContent, options.declaration);
 }
 /**
  * Extracts inline schema types from the generated `schemas` block.
@@ -69,12 +71,16 @@ export async function generateTypes(schema) {
  *
  * And replaces the inline body in `schemas` with a reference to the new type.
  *
+ * The definitions holding the schemas shared between the other definitions are lifted the
+ * same way, whether they hold an object or, as the hoisted enums and filter values do, a
+ * union of their own.
+ *
  * @param {string} typeContent - The generated TypeScript type content as a string.
- * @param {string[]} sharedEnums - The names of the definitions holding the enums shared
+ * @param {string[]} sharedTypes - The names of the definitions holding the schemas shared
  * between the other definitions, whose references are replaced by the name alone.
  * @return {string} The transformed types content with extracted schema types.
  */
-function extractSchemaTypes(typeContent, sharedEnums = []) {
+function extractSchemaTypes(typeContent, sharedTypes = []) {
     const extractedTypes = [];
     const typeNames = new Set();
     const entries = [];
@@ -140,8 +146,11 @@ function extractSchemaTypes(typeContent, sharedEnums = []) {
         }
     }
     updatedBaseContent += normalizedTypes.slice(cursor);
+    // Lift the shared definitions holding a union rather than an object, which the
+    // entries above leave in place (i.e. `QueryFilterValue: QueryFilterScalar | ...;`)
+    updatedBaseContent = extractSharedTypes(updatedBaseContent, sharedTypes, extractedTypes, typeNames);
     // Replace all cross-references like components["schemas"]["def-89"] with the type name
-    const references = new Map(sharedEnums.map((name) => [`"${name}"`, name]));
+    const references = new Map(sharedTypes.map((name) => [`"${name}"`, name]));
     for (const [defKey, typeName] of defToTypeName) {
         references.set(defKey, typeName);
     }
@@ -176,6 +185,87 @@ function extractSchemaTypes(typeContent, sharedEnums = []) {
     const mergedExtractedTypes = stripFormat(joined.replace(doubleCommentsRegex, '$1*'));
     return updatedBaseContent + '\n' + mergedExtractedTypes;
 }
+/**
+ * Lifts the shared definitions holding a type of their own out of the generated `schemas`
+ * block, so the type they hold is declared once and referenced by name everywhere else.
+ *
+ * Finds entries like:
+ *   QueryFilterValue: QueryFilterScalar | QueryFilterScalar[] | QueryCondition;
+ *
+ * Lifts each one into:
+ *   export type QueryFilterValue = QueryFilterScalar | QueryFilterScalar[] | QueryCondition;
+ *
+ * The definitions holding nothing but a reference to a type declared elsewhere, as the hoisted
+ * enums do, are left alone.
+ *
+ * @param {string} content - The generated types, with the object definitions already extracted.
+ * @param {string[]} names - The names of the shared definitions to lift.
+ * @param {string[]} extractedTypes - The extracted types, appended to for every lifted entry.
+ * @param {Set<string>} typeNames - The names already extracted, added to for every lifted entry.
+ * @return {string} The types with the body of every lifted entry replaced by its name.
+ */
+function extractSharedTypes(content, names, extractedTypes, typeNames) {
+    // The definitions live in the components block, so a property named after one of them
+    // elsewhere in the types is never mistaken for its declaration
+    const componentsStart = content.indexOf('export type components');
+    if (componentsStart < 0) {
+        return content;
+    }
+    for (const name of names) {
+        if (typeNames.has(name)) {
+            continue;
+        }
+        // The entry starts on a line of its own, optionally preceded by the JSDoc header
+        // holding the name of the definition
+        const entry = new RegExp(String.raw `\n[ \t]*(?:\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*)?${name}: `).exec(content.slice(componentsStart));
+        if (!entry) {
+            continue;
+        }
+        const start = componentsStart + entry.index + entry[0].length;
+        const end = findTypeEnd(content, start);
+        const body = content.slice(start, end).trim();
+        // A definition referencing a type declared elsewhere holds nothing to lift
+        if (!body || body === name) {
+            continue;
+        }
+        typeNames.add(name);
+        extractedTypes.push(`export type ${name} = ${body};\n`);
+        content = content.slice(0, start) + name + content.slice(end);
+    }
+    return content;
+}
+/**
+ * Finds the end of the type starting at the given index, which is the first semicolon that is
+ * not nested inside braces, brackets, parentheses or a string literal.
+ *
+ * @param {string} content - The content holding the type.
+ * @param {number} start - The index the type starts at.
+ * @return {number} The index of the semicolon terminating the type.
+ */
+function findTypeEnd(content, start) {
+    const closing = { '{': '}', '[': ']', '(': ')' };
+    const stack = [];
+    for (let i = start; i < content.length; i++) {
+        const character = content[i];
+        if (character === '"' || character === "'") {
+            i = content.indexOf(character, i + 1);
+            if (i < 0) {
+                return content.length;
+            }
+            continue;
+        }
+        if (closing[character]) {
+            stack.push(closing[character]);
+        }
+        else if (character === stack[stack.length - 1]) {
+            stack.pop();
+        }
+        else if (character === ';' && stack.length === 0) {
+            return i;
+        }
+    }
+    return content.length;
+}
 /**
  * Deduplicates and simplifies union type constituents in the provided TypeScript Abstract Syntax Tree (AST).
  * Ensures that duplicate constituents are removed and shared types across parenthesized union branches are hoisted.

package/esm/types/generator.d.ts

@@ -0,0 +1,6 @@
+/** Options controlling how the TypeScript types are generated from an OpenAPI schema. */
+export type GenerateTypesOptions = {
+    /** Whether the types are written into a declaration (`.d.ts`) file, which holds no runtime
+     * values and so declares the enum constants instead of initializing them. (default: false) */
+    declaration?: boolean;
+};

package/esm/types/generator.js

@@ -0,0 +1 @@
+export {};

package/esm/types/index.d.ts

@@ -1 +1,2 @@
+export * from './generator.js';
 export * from './routes.js';

package/esm/types/index.js

@@ -1 +1,2 @@
+export * from './generator.js';
 export * from './routes.js';

package/esm/utils/enum-util.d.ts

@@ -1,22 +1,22 @@
-import { OpenAPI3 } from 'openapi-typescript';
 /**
- * Hoists the inline enums a schema repeats across its definitions into shared definitions
- * of their own, replacing every occurrence with a reference to the hoisted definition.
+ * Rewrites the TypeScript enums of the generated types into a constant object holding the
+ * members and a type alias of their values, so both forms are accepted wherever the enum is
+ * used (i.e. `SortDirection.asc` and the plain `'asc'` literal alike).
  *
- * An Appweaver schema declares the same enum inline over and over, once per property that
- * accepts it, and each of them would otherwise become an enum of its own in the generated
- * types (i.e. a separate `asc | desc` enum for every sortable field of every resource).
+ * A TypeScript `enum` declares a nominal type, which rejects the very literals it is built
+ * from, forcing users of the generated client to import the enum for a value the API
+ * documents as a string. The rewritten declaration keeps the member access working while
+ * typing the property as the union of its values:
  *
- * Only enums that are byte for byte identical are hoisted, so no property loses its
- * description, example or nullability along the way. The hoisted definition is named after
- * {@link SHARED_ENUM_NAMES} when its values are well known, and otherwise after the part
- * the declaring definitions have in common followed by the property name (i.e. `PostCreate`
- * and `PostSingle` declaring `status` give `PostStatus`). Enums whose name cannot be
- * resolved, or whose name is already taken, are left inline.
+ * ```ts
+ * export const SortDirection = { asc: 'asc', desc: 'desc' } as const;
+ * export type SortDirection = (typeof SortDirection)[keyof typeof SortDirection];
+ * ```
  *
- * The given schema is mutated in place.
- *
- * @param {OpenAPI3} schema The OpenAPI v3 schema to hoist the shared enums of.
- * @return {string[]} The names of the hoisted definitions, in the order they were created.
+ * @param {string} content The generated TypeScript types to rewrite the enums of.
+ * @param {boolean} [declaration=false] Whether the types are emitted into a declaration
+ * (`.d.ts`) file, which holds no runtime values and so declares the constant instead of
+ * initializing it.
+ * @return {string} The types with every enum declaration rewritten.
  */
-export declare function hoistSharedEnums(schema: OpenAPI3): string[];
+export declare function rewriteEnumsAsObjects(content: string, declaration?: boolean): string;