@appweaver/client 1.2.0 → 1.3.0

package/cjs/constants.d.ts

@@ -4,6 +4,10 @@ export declare const FRAMEWORKS: readonly ["fetch", "angular"];
 export declare const CONFIG_FIELD = "x-appweaver-config";
 /** Custom OpenAPI extension key used for extracting resources names from schema CRUD objects. */
 export declare const CONFIG_RESOURCE_FIELD = "x-appweaver-resource";
+/** Names given to the well-known enums an Appweaver schema repeats inline across its definitions.
+ * 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>;
 /** 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. */
@@ -19,7 +23,7 @@ export declare const RESOURCE_OPERATIONS: {
     readonly deleteFiles: "post";
 };
 /** Expected type keys for a resource used for type inference. */
-export declare const RESOURCE_TYPES: readonly ["single", "multiple", "create", "update", "queryRequest", "queryResponse", "aggregateRequest", "aggregateResponse", "exportRequest", "files", "fileUpload", "fileDelete"];
+export declare const RESOURCE_TYPES: readonly ["single", "multiple", "create", "update", "queryRequest", "queryResponse", "querySort", "aggregateRequest", "aggregateResponse", "exportRequest", "files", "fileUpload", "fileDelete"];
 /** Type name used when generating the TypeScript module type for the auth module. */
 export declare const AUTH_MODULE_TYPE = "AuthModuleType";
 /** Maps auth operation names to HTTP methods used for matchingOpenAPI paths to `AuthClient` methods.

package/cjs/constants.js

@@ -3,13 +3,19 @@
 // They are typically only modified when changes occur in other Appweaver packages
 // (such as core and common) to reflect new route paths or methods.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FILE_OPERATIONS = exports.HEALTH_TYPES = exports.HEALTH_OPERATIONS = exports.HEALTH_MODULE_TYPE = exports.ACCOUNT_TYPES = exports.ACCOUNT_OPERATIONS = exports.ACCOUNT_MODULE_TYPE = exports.AUTH_TYPES = exports.AUTH_OPERATIONS = exports.AUTH_MODULE_TYPE = exports.RESOURCE_TYPES = exports.RESOURCE_OPERATIONS = exports.RESOURCE_MODULE_TYPE = exports.CONFIG_RESOURCE_FIELD = exports.CONFIG_FIELD = exports.FRAMEWORKS = void 0;
+exports.FILE_OPERATIONS = exports.HEALTH_TYPES = exports.HEALTH_OPERATIONS = exports.HEALTH_MODULE_TYPE = exports.ACCOUNT_TYPES = exports.ACCOUNT_OPERATIONS = exports.ACCOUNT_MODULE_TYPE = exports.AUTH_TYPES = exports.AUTH_OPERATIONS = exports.AUTH_MODULE_TYPE = exports.RESOURCE_TYPES = exports.RESOURCE_OPERATIONS = exports.RESOURCE_MODULE_TYPE = exports.SHARED_ENUM_NAMES = exports.CONFIG_RESOURCE_FIELD = exports.CONFIG_FIELD = exports.FRAMEWORKS = void 0;
 /** Supported frameworks for generating the client class. */
 exports.FRAMEWORKS = ['fetch', 'angular'];
 /** Custom OpenAPI extension key used for extracting route prefixes and base paths to their resources. */
 exports.CONFIG_FIELD = 'x-appweaver-config';
 /** Custom OpenAPI extension key used for extracting resources names from schema CRUD objects. */
 exports.CONFIG_RESOURCE_FIELD = 'x-appweaver-resource';
+/** Names given to the well-known enums an Appweaver schema repeats inline across its definitions.
+ * 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. */
+exports.SHARED_ENUM_NAMES = {
+    'asc|desc': 'SortDirection'
+};
 /** Suffix used when generating the TypeScript module type name for a resource. */
 exports.RESOURCE_MODULE_TYPE = 'ResourceModuleType';
 /** Maps CRUD operation names to HTTP methods used for matching OpenAPI paths to `ResourceClient` methods. */
@@ -32,6 +38,7 @@ exports.RESOURCE_TYPES = [
     'update',
     'queryRequest',
     'queryResponse',
+    'querySort',
     'aggregateRequest',
     'aggregateResponse',
     'exportRequest',

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

@@ -3,7 +3,7 @@ import { OpenAPI3 } from 'openapi-typescript';
  * 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 already parsed OpenAPI3 object.
+ * representing JSON or YAML format, or an already parsed OpenAPI3 object.
  * @return {Promise<string>} A promise that resolves to a string containing the generated TypeScript types.
  */
 export declare function generateTypes(schema: string | OpenAPI3): Promise<string>;

package/cjs/generators/generate-types.js

@@ -45,11 +45,16 @@ const constants_1 = require("../constants");
  * 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 already parsed OpenAPI3 object.
+ * representing JSON or YAML format, or an already parsed OpenAPI3 object.
  * @return {Promise<string>} A promise that resolves to a string containing the generated TypeScript types.
  */
 async function generateTypes(schema) {
-    const schemaObject = typeof schema === 'string' ? await (0, utils_1.toSchemaObject)(schema) : schema;
+    // The schema is copied before the shared enums are hoisted into it, so the
+    // caller keeps the schema it passed in unchanged
+    const schemaObject = typeof schema === 'string'
+        ? await (0, utils_1.toSchemaObject)(schema)
+        : structuredClone(schema);
+    const sharedEnums = (0, utils_1.hoistSharedEnums)(schemaObject);
     const ast = await (0, openapi_typescript_1.default)(schemaObject, {
         exportType: true,
         emptyObjectsUnknown: true,
@@ -86,7 +91,7 @@ async function generateTypes(schema) {
         }
     });
     let typesContent = (0, openapi_typescript_1.astToString)(deduplicateUnionConstituents(ast));
-    typesContent = extractSchemaTypes(typesContent);
+    typesContent = extractSchemaTypes(typesContent, sharedEnums);
     typesContent = combineModuleTypes(typesContent, schemaObject);
     typesContent = deduplicateExportedTypes(typesContent);
     return replaceFileUploadTypes(typesContent);
@@ -104,20 +109,26 @@ async function generateTypes(schema) {
  * And replaces the inline body in `schemas` with a reference to the new type.
  *
  * @param {string} typeContent - The generated TypeScript type content as a string.
+ * @param {string[]} sharedEnums - The names of the definitions holding the enums 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) {
-    // Matches the header: /** TypeName */ "def-N": <cursor here before the opening brace>
+function extractSchemaTypes(typeContent, sharedEnums = []) {
     const extractedTypes = [];
     const typeNames = new Set();
     const entries = [];
     // Maps "def-N" key → extracted type name, used to replace cross-references
     const defToTypeName = new Map();
+    // Matches the JSDoc header of a definition, capturing its name, which is the first
+    // word of the comment, whether it stands alone or is followed by the description and
+    // the tags of the definition. The body of the comment is matched one character at a
+    // time, so that a header never spans the comments of the definitions before it.
+    const headerComment = String.raw `\/\*\*[\s*]*(\w+)(?:(?!\*\/)[\s\S])*\*\/`;
     // Replace Record<...> types with object types so schema type can be extracted
-    const normalizedTypes = typeContent.replace(/(\/\*\*\s*\w+\s*\*\/\s*"def-\d+"):\s*Record<(\w+), (\w+)>;/g, `$1: { [key: $2]: $3 };`);
+    const normalizedTypes = typeContent.replace(new RegExp(`(${headerComment}\\s*"def-\\d+"):\\s*Record<(\\w+), (\\w+)>;`, 'g'), `$1: { [key: $3]: $4 };`);
     let m;
     // Also capture the "def-N" key from the header
-    const headerPatternWithKey = /\/\*\*\s*(\w+)\s*\*\/\s*("def-\d+"):\s*(?=\{)/g;
+    const headerPatternWithKey = new RegExp(`${headerComment}\\s*("def-\\d+"):\\s*(?=\\{)`, 'g');
     while ((m = headerPatternWithKey.exec(normalizedTypes)) !== null) {
         const typeName = m[1];
         const defKey = m[2]; // e.g. "def-89"
@@ -168,40 +179,31 @@ function extractSchemaTypes(typeContent) {
         }
     }
     updatedBaseContent += normalizedTypes.slice(cursor);
-    const enumDefPrefixType = {};
     // Replace all cross-references like components["schemas"]["def-89"] with the type name
-    // Also, extract all enum prefixes in a list
+    const references = new Map(sharedEnums.map((name) => [`"${name}"`, name]));
     for (const [defKey, typeName] of defToTypeName) {
+        references.set(defKey, typeName);
+    }
+    for (const [defKey, typeName] of references) {
         // The defKey already includes surrounding quotes, e.g. "def-89"
         const refPattern = new RegExp(`components\\["schemas"]\\[${defKey}\\]`, 'g');
         updatedBaseContent = updatedBaseContent.replace(refPattern, typeName);
         extractedTypes.forEach((t, idx) => {
             extractedTypes[idx] = t.replace(refPattern, typeName);
         });
-        // Extract defKey prefix for enums to be replaced them with type name
-        const defKeyPrefix = defKey
-            .replace(/"/g, '')
-            .replace(/(^|-)([a-z])/g, (_, __, ch) => ch.toUpperCase())
-            .replace(/-(\d+)/g, '$1');
-        enumDefPrefixType[defKeyPrefix] = typeName;
-    }
-    const getFirstNumber = (value) => {
-        const match = value.match(/\d+/);
-        return match ? Number(match[0]) : -Infinity;
-    };
-    // Sort keys descending by definition ID number if present. This is required
-    // to prevent replacing the prefix 'Def125' with 'Def12' or 'Def1' sub-prefix.
-    const sortedEnumKeys = Object.keys(enumDefPrefixType).sort((a, b) => getFirstNumber(b) - getFirstNumber(a));
-    // Replace enum definition prefixes with corresponding type names
-    for (const prefix of sortedEnumKeys) {
-        const typeName = enumDefPrefixType[prefix];
-        const exportEnumPattern = new RegExp(`export enum ${prefix}(.*){`, 'g');
-        updatedBaseContent = updatedBaseContent.replace(exportEnumPattern, `export enum ${typeName}$1{`);
-        const referenceEnumPattern = new RegExp(`: ${prefix}(.*);`, 'g');
-        extractedTypes.forEach((t, idx) => {
-            extractedTypes[idx] = t.replace(referenceEnumPattern, `: ${typeName}$1;`);
-        });
     }
+    // Rename the enums generated for the properties of a definition (i.e. `Def89Status`)
+    // after the type extracted from it (i.e. `PostSingleStatus`), declarations and
+    // references alike. The digits are matched as a whole, so a definition number is never
+    // mistaken for the prefix of a longer one (i.e. `Def12` inside of `Def125Status`).
+    const renameEnums = (content) => content.replace(/\bDef(\d+)([A-Z]\w*)\b/g, (match, id, property) => {
+        const typeName = defToTypeName.get(`"def-${id}"`);
+        return typeName ? `${typeName}${property}` : match;
+    });
+    updatedBaseContent = renameEnums(updatedBaseContent);
+    extractedTypes.forEach((t, idx) => {
+        extractedTypes[idx] = renameEnums(t);
+    });
     // Remove redundant "Format: ..." prose lines since the @format tag already captures this.
     // If the line ends with */ (end-of-comment), preserve the closing; otherwise remove entirely.
     const redundantFormatRegex = /\n(\s*)\* Format: [^\n]*/g;

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

@@ -0,0 +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.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function hoistSharedEnums(schema: OpenAPI3): string[];

package/cjs/utils/enum-util.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hoistSharedEnums = hoistSharedEnums;
+const constants_1 = require("../constants");
+/**
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * 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.
+ */
+function hoistSharedEnums(schema) {
+    const definitions = schema.components?.schemas;
+    if (!definitions) {
+        return [];
+    }
+    // Enums declared by identical schema content, keyed by that content
+    const groups = new Map();
+    for (const [key, definition] of Object.entries(definitions)) {
+        if (definition && typeof definition === 'object') {
+            const owner = definition['title'];
+            collectEnums(definition, typeof owner === 'string' ? owner : key, '', groups);
+        }
+    }
+    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 [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 { container, key } of occurrences) {
+            container[key] = {
+                $ref: `#/components/schemas/${name}`
+            };
+        }
+    }
+    return hoistedNames;
+}
+/**
+ * Collects every inline enum declared below the given schema node into the groups map,
+ * keyed by the stable serialization of the enum schema, so identical enums group together.
+ *
+ * @param {SchemaContainer} container The schema node to collect the enums 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 {Map<string, EnumOccurrence[]>} groups The collected occurrences, grouped by content.
+ */
+function collectEnums(container, owner, property, 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)) {
+                visitSchema(properties, name, owner, name, groups);
+            }
+            continue;
+        }
+        visitSchema(container, key, owner, property, groups);
+    }
+}
+/**
+ * Records the schema held by the container under the given key as an enum occurrence, or
+ * descends into it when it declares no enum of its own.
+ *
+ * @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 {Map<string, EnumOccurrence[]>} groups The collected occurrences, grouped by content.
+ */
+function visitSchema(container, key, owner, property, groups) {
+    const node = container[key];
+    if (Array.isArray(node['enum'])) {
+        const content = stableStringify(node);
+        const occurrences = groups.get(content) ?? [];
+        occurrences.push({ container, key, owner, property });
+        groups.set(content, occurrences);
+        return;
+    }
+    collectEnums(node, owner, property, 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 {Record<string, unknown>} node The enum schema to resolve the name of.
+ * @param {EnumOccurrence[]} 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('');
+}
+/**
+ * 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 +1,2 @@
+export * from './enum-util';
 export * from './schema-util';

package/cjs/utils/index.js

@@ -14,4 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./enum-util"), exports);
 __exportStar(require("./schema-util"), exports);

package/esm/constants.d.ts

@@ -4,6 +4,10 @@ export declare const FRAMEWORKS: readonly ["fetch", "angular"];
 export declare const CONFIG_FIELD = "x-appweaver-config";
 /** Custom OpenAPI extension key used for extracting resources names from schema CRUD objects. */
 export declare const CONFIG_RESOURCE_FIELD = "x-appweaver-resource";
+/** Names given to the well-known enums an Appweaver schema repeats inline across its definitions.
+ * 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>;
 /** 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. */
@@ -19,7 +23,7 @@ export declare const RESOURCE_OPERATIONS: {
     readonly deleteFiles: "post";
 };
 /** Expected type keys for a resource used for type inference. */
-export declare const RESOURCE_TYPES: readonly ["single", "multiple", "create", "update", "queryRequest", "queryResponse", "aggregateRequest", "aggregateResponse", "exportRequest", "files", "fileUpload", "fileDelete"];
+export declare const RESOURCE_TYPES: readonly ["single", "multiple", "create", "update", "queryRequest", "queryResponse", "querySort", "aggregateRequest", "aggregateResponse", "exportRequest", "files", "fileUpload", "fileDelete"];
 /** Type name used when generating the TypeScript module type for the auth module. */
 export declare const AUTH_MODULE_TYPE = "AuthModuleType";
 /** Maps auth operation names to HTTP methods used for matchingOpenAPI paths to `AuthClient` methods.

package/esm/constants.js

@@ -7,6 +7,12 @@ export const FRAMEWORKS = ['fetch', 'angular'];
 export const CONFIG_FIELD = 'x-appweaver-config';
 /** Custom OpenAPI extension key used for extracting resources names from schema CRUD objects. */
 export const CONFIG_RESOURCE_FIELD = 'x-appweaver-resource';
+/** Names given to the well-known enums an Appweaver schema repeats inline across its definitions.
+ * 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 const SHARED_ENUM_NAMES = {
+    'asc|desc': 'SortDirection'
+};
 /** 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. */
@@ -29,6 +35,7 @@ export const RESOURCE_TYPES = [
     'update',
     'queryRequest',
     'queryResponse',
+    'querySort',
     'aggregateRequest',
     'aggregateResponse',
     'exportRequest',

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

@@ -3,7 +3,7 @@ import { OpenAPI3 } from 'openapi-typescript';
  * 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 already parsed OpenAPI3 object.
+ * representing JSON or YAML format, or an already parsed OpenAPI3 object.
  * @return {Promise<string>} A promise that resolves to a string containing the generated TypeScript types.
  */
 export declare function generateTypes(schema: string | OpenAPI3): Promise<string>;

package/esm/generators/generate-types.js

@@ -1,16 +1,21 @@
 import openapiTS, { astToString } from 'openapi-typescript';
 import ts from 'typescript';
-import { toSchemaObject } from '../utils/index.js';
+import { hoistSharedEnums, 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 already parsed OpenAPI3 object.
+ * representing JSON or YAML format, or an already parsed OpenAPI3 object.
  * @return {Promise<string>} A promise that resolves to a string containing the generated TypeScript types.
  */
 export async function generateTypes(schema) {
-    const schemaObject = typeof schema === 'string' ? await toSchemaObject(schema) : schema;
+    // The schema is copied before the shared enums 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 ast = await openapiTS(schemaObject, {
         exportType: true,
         emptyObjectsUnknown: true,
@@ -47,7 +52,7 @@ export async function generateTypes(schema) {
         }
     });
     let typesContent = astToString(deduplicateUnionConstituents(ast));
-    typesContent = extractSchemaTypes(typesContent);
+    typesContent = extractSchemaTypes(typesContent, sharedEnums);
     typesContent = combineModuleTypes(typesContent, schemaObject);
     typesContent = deduplicateExportedTypes(typesContent);
     return replaceFileUploadTypes(typesContent);
@@ -65,20 +70,26 @@ export async function generateTypes(schema) {
  * And replaces the inline body in `schemas` with a reference to the new type.
  *
  * @param {string} typeContent - The generated TypeScript type content as a string.
+ * @param {string[]} sharedEnums - The names of the definitions holding the enums 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) {
-    // Matches the header: /** TypeName */ "def-N": <cursor here before the opening brace>
+function extractSchemaTypes(typeContent, sharedEnums = []) {
     const extractedTypes = [];
     const typeNames = new Set();
     const entries = [];
     // Maps "def-N" key → extracted type name, used to replace cross-references
     const defToTypeName = new Map();
+    // Matches the JSDoc header of a definition, capturing its name, which is the first
+    // word of the comment, whether it stands alone or is followed by the description and
+    // the tags of the definition. The body of the comment is matched one character at a
+    // time, so that a header never spans the comments of the definitions before it.
+    const headerComment = String.raw `\/\*\*[\s*]*(\w+)(?:(?!\*\/)[\s\S])*\*\/`;
     // Replace Record<...> types with object types so schema type can be extracted
-    const normalizedTypes = typeContent.replace(/(\/\*\*\s*\w+\s*\*\/\s*"def-\d+"):\s*Record<(\w+), (\w+)>;/g, `$1: { [key: $2]: $3 };`);
+    const normalizedTypes = typeContent.replace(new RegExp(`(${headerComment}\\s*"def-\\d+"):\\s*Record<(\\w+), (\\w+)>;`, 'g'), `$1: { [key: $3]: $4 };`);
     let m;
     // Also capture the "def-N" key from the header
-    const headerPatternWithKey = /\/\*\*\s*(\w+)\s*\*\/\s*("def-\d+"):\s*(?=\{)/g;
+    const headerPatternWithKey = new RegExp(`${headerComment}\\s*("def-\\d+"):\\s*(?=\\{)`, 'g');
     while ((m = headerPatternWithKey.exec(normalizedTypes)) !== null) {
         const typeName = m[1];
         const defKey = m[2]; // e.g. "def-89"
@@ -129,40 +140,31 @@ function extractSchemaTypes(typeContent) {
         }
     }
     updatedBaseContent += normalizedTypes.slice(cursor);
-    const enumDefPrefixType = {};
     // Replace all cross-references like components["schemas"]["def-89"] with the type name
-    // Also, extract all enum prefixes in a list
+    const references = new Map(sharedEnums.map((name) => [`"${name}"`, name]));
     for (const [defKey, typeName] of defToTypeName) {
+        references.set(defKey, typeName);
+    }
+    for (const [defKey, typeName] of references) {
         // The defKey already includes surrounding quotes, e.g. "def-89"
         const refPattern = new RegExp(`components\\["schemas"]\\[${defKey}\\]`, 'g');
         updatedBaseContent = updatedBaseContent.replace(refPattern, typeName);
         extractedTypes.forEach((t, idx) => {
             extractedTypes[idx] = t.replace(refPattern, typeName);
         });
-        // Extract defKey prefix for enums to be replaced them with type name
-        const defKeyPrefix = defKey
-            .replace(/"/g, '')
-            .replace(/(^|-)([a-z])/g, (_, __, ch) => ch.toUpperCase())
-            .replace(/-(\d+)/g, '$1');
-        enumDefPrefixType[defKeyPrefix] = typeName;
-    }
-    const getFirstNumber = (value) => {
-        const match = value.match(/\d+/);
-        return match ? Number(match[0]) : -Infinity;
-    };
-    // Sort keys descending by definition ID number if present. This is required
-    // to prevent replacing the prefix 'Def125' with 'Def12' or 'Def1' sub-prefix.
-    const sortedEnumKeys = Object.keys(enumDefPrefixType).sort((a, b) => getFirstNumber(b) - getFirstNumber(a));
-    // Replace enum definition prefixes with corresponding type names
-    for (const prefix of sortedEnumKeys) {
-        const typeName = enumDefPrefixType[prefix];
-        const exportEnumPattern = new RegExp(`export enum ${prefix}(.*){`, 'g');
-        updatedBaseContent = updatedBaseContent.replace(exportEnumPattern, `export enum ${typeName}$1{`);
-        const referenceEnumPattern = new RegExp(`: ${prefix}(.*);`, 'g');
-        extractedTypes.forEach((t, idx) => {
-            extractedTypes[idx] = t.replace(referenceEnumPattern, `: ${typeName}$1;`);
-        });
     }
+    // Rename the enums generated for the properties of a definition (i.e. `Def89Status`)
+    // after the type extracted from it (i.e. `PostSingleStatus`), declarations and
+    // references alike. The digits are matched as a whole, so a definition number is never
+    // mistaken for the prefix of a longer one (i.e. `Def12` inside of `Def125Status`).
+    const renameEnums = (content) => content.replace(/\bDef(\d+)([A-Z]\w*)\b/g, (match, id, property) => {
+        const typeName = defToTypeName.get(`"def-${id}"`);
+        return typeName ? `${typeName}${property}` : match;
+    });
+    updatedBaseContent = renameEnums(updatedBaseContent);
+    extractedTypes.forEach((t, idx) => {
+        extractedTypes[idx] = renameEnums(t);
+    });
     // Remove redundant "Format: ..." prose lines since the @format tag already captures this.
     // If the line ends with */ (end-of-comment), preserve the closing; otherwise remove entirely.
     const redundantFormatRegex = /\n(\s*)\* Format: [^\n]*/g;

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

@@ -0,0 +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.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function hoistSharedEnums(schema: OpenAPI3): string[];

package/esm/utils/enum-util.js

@@ -0,0 +1,176 @@
+import { SHARED_ENUM_NAMES } from '../constants.js';
+/**
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * 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.
+ */
+export function hoistSharedEnums(schema) {
+    const definitions = schema.components?.schemas;
+    if (!definitions) {
+        return [];
+    }
+    // Enums declared by identical schema content, keyed by that content
+    const groups = new Map();
+    for (const [key, definition] of Object.entries(definitions)) {
+        if (definition && typeof definition === 'object') {
+            const owner = definition['title'];
+            collectEnums(definition, typeof owner === 'string' ? owner : key, '', groups);
+        }
+    }
+    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 [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 { container, key } of occurrences) {
+            container[key] = {
+                $ref: `#/components/schemas/${name}`
+            };
+        }
+    }
+    return hoistedNames;
+}
+/**
+ * Collects every inline enum declared below the given schema node into the groups map,
+ * keyed by the stable serialization of the enum schema, so identical enums group together.
+ *
+ * @param {SchemaContainer} container The schema node to collect the enums 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 {Map<string, EnumOccurrence[]>} groups The collected occurrences, grouped by content.
+ */
+function collectEnums(container, owner, property, 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)) {
+                visitSchema(properties, name, owner, name, groups);
+            }
+            continue;
+        }
+        visitSchema(container, key, owner, property, groups);
+    }
+}
+/**
+ * Records the schema held by the container under the given key as an enum occurrence, or
+ * descends into it when it declares no enum of its own.
+ *
+ * @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 {Map<string, EnumOccurrence[]>} groups The collected occurrences, grouped by content.
+ */
+function visitSchema(container, key, owner, property, groups) {
+    const node = container[key];
+    if (Array.isArray(node['enum'])) {
+        const content = stableStringify(node);
+        const occurrences = groups.get(content) ?? [];
+        occurrences.push({ container, key, owner, property });
+        groups.set(content, occurrences);
+        return;
+    }
+    collectEnums(node, owner, property, 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 {Record<string, unknown>} node The enum schema to resolve the name of.
+ * @param {EnumOccurrence[]} 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 = 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('');
+}
+/**
+ * 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/esm/utils/index.d.ts

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

package/esm/utils/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appweaver/client",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Appweaver - the backend framework for AI-first development (@client)",
   "author": "Luka Matosevic",
   "license": "MIT",
@@ -49,7 +49,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">= 20"
+    "node": ">= 22"
   },
   "scripts": {
     "weaver-client": "node ./dist/cjs/weaver-client.js"