@appweaver/client 1.3.0 → 1.4.0

package/esm/clients/modules/resource-client.d.ts

@@ -2,6 +2,7 @@ import { BaseModule, RequestOptions } from './base-module.js';
 import { BaseClientInterface } from '../base-client-interface.js';
 import { FileDataResponse } from '../responses/index.js';
 import { RESOURCE_OPERATIONS, RESOURCE_TYPES } from '../../constants.js';
+import { ResourceId } from '../../types/index.js';
 export type ResourceType = Record<(typeof RESOURCE_TYPES)[number], unknown>;
 export type ResourceInterface = {
     [K in keyof typeof RESOURCE_OPERATIONS]: (...args: any[]) => Promise<any>;
@@ -10,13 +11,13 @@ export declare class ResourceClient<Resource extends ResourceType> extends BaseM
     readonly basePath: string;
     constructor(client: BaseClientInterface, basePath: string);
     /**
-     * Fetches a single resource by its numeric ID.
+     * Fetches a single resource by its ID.
      *
-     * @param {number} id - The ID of the resource to retrieve.
+     * @param {ResourceId} id - The ID of the resource to retrieve.
      * @param {RequestOptions} options - Additional request options (headers, query params, etc.).
      * @returns The resource record matching the given ID.
      */
-    find(id: number, options?: RequestOptions): Promise<Resource['single']>;
+    find(id: ResourceId, options?: RequestOptions): Promise<Resource['single']>;
     /**
      * Executes a query against the resource collection.
      *
@@ -49,16 +50,16 @@ export declare class ResourceClient<Resource extends ResourceType> extends BaseM
      * @returns The updated resource record.
      */
     update(resource: Resource['update'] & {
-        id: number;
+        id: ResourceId;
     }, options?: RequestOptions): Promise<Resource['single']>;
     /**
-     * Deletes a resource record by its numeric ID.
+     * Deletes a resource record by its ID.
      *
-     * @param {number} id - The ID of the resource to delete.
+     * @param {ResourceId} id - The ID of the resource to delete.
      * @param {RequestOptions} options - Additional request options.
      * @returns The deleted resource record.
      */
-    delete(id: number, options?: RequestOptions): Promise<Resource['single']>;
+    delete(id: ResourceId, options?: RequestOptions): Promise<Resource['single']>;
     /**
      * Exports resource records as a file (e.g., CSV) and returns a streaming response.
      *
@@ -72,19 +73,19 @@ export declare class ResourceClient<Resource extends ResourceType> extends BaseM
      *
      * Each entry in `files` maps a field name to a single `File` or an array of `File` objects.
      *
-     * @param {number} id - The ID of the resource for which to upload files.
+     * @param {ResourceId} id - The ID of the resource for which to upload files.
      * @param {Object} files - A map of field names to the file(s) to upload.
      * @param {RequestOptions} options - Additional request options.
      * @returns The updated file metadata for the resource.
      */
-    uploadFiles(id: number, files: Resource['fileUpload'], options?: RequestOptions): Promise<Resource['files']>;
+    uploadFiles(id: ResourceId, files: Resource['fileUpload'], options?: RequestOptions): Promise<Resource['files']>;
     /**
      * Removes specific files from the resource record.
      *
-     * @param {number} id - The ID of the resource for which to delete files.
+     * @param {ResourceId} id - The ID of the resource for which to delete files.
      * @param {Object} files - The file deletion payload identifying which files to remove.
      * @param {RequestOptions} options - Additional request options.
      * @returns The updated file metadata for the resource after deletion.
      */
-    deleteFiles(id: number, files: Resource['fileDelete'], options?: RequestOptions): Promise<Resource['files']>;
+    deleteFiles(id: ResourceId, files: Resource['fileDelete'], options?: RequestOptions): Promise<Resource['files']>;
 }

package/esm/clients/modules/resource-client.js

@@ -6,9 +6,9 @@ export class ResourceClient extends BaseModule {
         this.basePath = basePath;
     }
     /**
-     * Fetches a single resource by its numeric ID.
+     * Fetches a single resource by its ID.
      *
-     * @param {number} id - The ID of the resource to retrieve.
+     * @param {ResourceId} id - The ID of the resource to retrieve.
      * @param {RequestOptions} options - Additional request options (headers, query params, etc.).
      * @returns The resource record matching the given ID.
      */
@@ -82,9 +82,9 @@ export class ResourceClient extends BaseModule {
         });
     }
     /**
-     * Deletes a resource record by its numeric ID.
+     * Deletes a resource record by its ID.
      *
-     * @param {number} id - The ID of the resource to delete.
+     * @param {ResourceId} id - The ID of the resource to delete.
      * @param {RequestOptions} options - Additional request options.
      * @returns The deleted resource record.
      */
@@ -122,7 +122,7 @@ export class ResourceClient extends BaseModule {
      *
      * Each entry in `files` maps a field name to a single `File` or an array of `File` objects.
      *
-     * @param {number} id - The ID of the resource for which to upload files.
+     * @param {ResourceId} id - The ID of the resource for which to upload files.
      * @param {Object} files - A map of field names to the file(s) to upload.
      * @param {RequestOptions} options - Additional request options.
      * @returns The updated file metadata for the resource.
@@ -153,7 +153,7 @@ export class ResourceClient extends BaseModule {
     /**
      * Removes specific files from the resource record.
      *
-     * @param {number} id - The ID of the resource for which to delete files.
+     * @param {ResourceId} id - The ID of the resource for which to delete files.
      * @param {Object} files - The file deletion payload identifying which files to remove.
      * @param {RequestOptions} options - Additional request options.
      * @returns The updated file metadata for the resource after deletion.

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/index.d.ts

@@ -1,2 +1,3 @@
 export * from './clients/index.js';
 export * from './errors/index.js';
+export * from './types/resource.js';

package/esm/index.js

@@ -1,2 +1,3 @@
 export * from './clients/index.js';
 export * from './errors/index.js';
+export * from './types/resource.js';

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,3 @@
+export * from './generator.js';
+export * from './resource.js';
 export * from './routes.js';

package/esm/types/index.js

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

package/esm/types/resource.d.ts

@@ -0,0 +1,2 @@
+/** Primary key value: a number for `int` and `bigInt` ids, a string for `string` ids */
+export type ResourceId = number | string;

package/esm/types/resource.js

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

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;