@ahoo-wang/wow-generator 9.2.0-rc.0

package/dist/wow/conventions.d.ts

@@ -0,0 +1,154 @@
+import { OpenAPI, Tag } from '@ahoo-wang/fetcher-openapi';
+import { AggregateDefinition, TagAliasAggregate } from './model.js';
+/** The oldest Wow server whose OpenAPI metadata the generator reads fully. */
+export declare const MINIMUM_WOW_VERSION = "8.10";
+/** The `info` extension naming the bounded context the document serves. */
+export declare const CONTEXT_ALIAS_EXTENSION = "x-wow-context-alias";
+/** The bounded context a document names, if it is a Wow service's. */
+export declare function contextAliasOf(openAPI: OpenAPI): string | undefined;
+/**
+ * Reads an aggregate off a tag named `<contextAlias>.<aggregateName>`.
+ *
+ * @param tagName - The tag name
+ * @returns `[contextAlias, aggregateName]`, or null when the tag names no aggregate
+ */
+export declare function isAliasAggregate(tagName: string): [string, string] | null;
+/**
+ * The aggregate a tag names, or null when it names none.
+ *
+ * @param tag - The tag
+ */
+export declare function tagToAggregate(tag: Tag): TagAliasAggregate | null;
+/**
+ * The command an operation sends, read off its id
+ * `<contextAlias>.<aggregateName>.<command>`.
+ *
+ * @param operationId - The operation id
+ * @returns The command name, or null when the id has another shape
+ */
+export declare function operationIdToCommandName(operationId?: string): string | null;
+/** The operation that sends any command; it belongs to no aggregate. */
+export declare const SEND_COMMAND_OPERATION_ID = "wow.command.send";
+/** The response every command operation answers with. */
+export declare const COMMAND_OK_RESPONSE_REF = "#/components/responses/wow.CommandOk";
+/** The operation id suffix of the operation that loads an aggregate's state. */
+export declare const STATE_OPERATION_SUFFIX = ".snapshot_state.single";
+/** The operation id suffix of the operation that lists an aggregate's events. */
+export declare const EVENTS_OPERATION_SUFFIX = ".event.list_query";
+/** The operation id suffix of the operation that counts snapshots by a condition. */
+export declare const FIELDS_OPERATION_SUFFIX = ".snapshot.count";
+/** The request body extension naming an aggregate's query fields (Wow 8.11.1+). */
+export declare const QUERY_FIELDS_EXTENSION = "x-wow-query-fields";
+/**
+ * The route segment of an aggregate, read off one of its snapshot routes:
+ * `/tenant/{tenantId}/owner/{ownerId}/sales-order/snapshot/count` →
+ * `sales-order`. It differs from the aggregate name when the aggregate sets
+ * a resource name (`@AggregateRoute(resourceName = "sales-order")`).
+ */
+export declare const SNAPSHOT_ROUTE: RegExp;
+/**
+ * The suffixes of the types Wow derives from an aggregate's state; the
+ * wow-client generics stand for them, so they generate no model.
+ */
+export declare const AGGREGATED_SCHEMA_SUFFIXES: readonly string[];
+/**
+ * The names of the types Wow derives from an aggregate's state model.
+ *
+ * @param stateName - The name of the state model
+ */
+export declare function aggregatedTypeNames(stateName: string): string[];
+/**
+ * Tells whether a schema is Wow's own, which wow-client already declares, so
+ * it generates no model: every `wow.` schema but the paged lists and operator
+ * maps of the query API, the aggregated query and event stream types, and
+ * the types derived from an aggregate's state.
+ *
+ * @param schemaKey - The schema's component key
+ * @param modelName - The name of the model the schema would generate, read
+ *   only when the key alone does not decide
+ * @param aggregatedNames - The names of the types derived from the aggregates' states
+ */
+export declare function isWowSchema(schemaKey: string, modelName: () => string, aggregatedNames: ReadonlySet<string>): boolean;
+/** Import path for the WOW framework types */
+export declare const IMPORT_WOW_PATH = "@ahoo-wang/wow-client";
+/**
+ * Import path for the deprecated Condition query model, which
+ * `@ahoo-wang/wow-client` keeps on its `/legacy` subpath for Wow 8.10 servers.
+ */
+export declare const IMPORT_WOW_LEGACY_PATH = "@ahoo-wang/wow-client/legacy";
+/** The mapped type names that `IMPORT_WOW_LEGACY_PATH` exports. */
+export declare const WOW_LEGACY_TYPES: ReadonlySet<string>;
+/** Mapping of OpenAPI schema keys to WOW framework types */
+export declare const WOW_TYPE_MAPPING: {
+    'wow.command.CommandResult': string;
+    'wow.command.CommandResultArray': string;
+    'wow.MessageHeaderSqlType': string;
+    'wow.api.BindingError': string;
+    'wow.api.DefaultErrorInfo': string;
+    'wow.api.RecoverableType': string;
+    'wow.api.command.DefaultDeleteAggregate': string;
+    'wow.api.command.DefaultRecoverAggregate': string;
+    'wow.api.abac.DefaultApplyResourceTags': string;
+    'wow.api.messaging.FunctionInfoData': string;
+    'wow.api.messaging.FunctionKind': string;
+    'wow.api.modeling.AggregateId': string;
+    'wow.api.query.Condition': string;
+    'wow.api.query.ConditionOptions': string;
+    'wow.api.query.ListQuery': string;
+    'wow.api.query.Operator': string;
+    'wow.api.query.PagedQuery': string;
+    'wow.api.query.Pagination': string;
+    'wow.api.query.Projection': string;
+    'wow.api.query.Sort': string;
+    'wow.api.query.Sort.Direction': string;
+    'wow.api.query.DynamicDocument': string;
+    'wow.api.query.DynamicDocumentArray': string;
+    'wow.command.CommandStage': string;
+    'wow.command.SimpleWaitSignal': string;
+    'wow.configuration.Aggregate': string;
+    'wow.configuration.BoundedContext': string;
+    'wow.configuration.WowMetadata': string;
+    'wow.modeling.DomainEvent': string;
+    'wow.openapi.BatchResult': string;
+    'wow.messaging.CompensationTarget': string;
+};
+/**
+ * The wow-client type a schema maps to, and the module that exports it.
+ *
+ * @param schemaKey - The schema's component key
+ * @param properties - The schema's properties, if the caller has the schema:
+ * a ListQuery or PagedQuery that carries `filter` is the filter model's
+ * @returns The type, or undefined when the schema is not one of Wow's own
+ */
+export declare function wowTypeOf(schemaKey: string, properties?: Record<string, unknown>): {
+    name: string;
+    path: string;
+} | undefined;
+/**
+ * Tags whose operations generate no API client: Wow's own endpoints and
+ * Spring's actuator. The tags of aggregates are left out as well; their
+ * operations go to the command and query clients.
+ */
+export declare const IGNORED_API_CLIENT_TAGS: ReadonlySet<string>;
+/**
+ * The resource-attribution path parameters Wow's CoSec interceptor fills,
+ * which generated clients therefore leave out.
+ */
+export declare const RESOURCE_ATTRIBUTION_PATH_PARAMETERS: readonly string[];
+/** The route prefix of a tenant's resources (wow-client `ResourceAttributionPathSpec.TENANT`). */
+export declare const TENANT_PATH_PREFIX = "/tenant/{tenantId}";
+/** The route prefix of an owner's resources (wow-client `ResourceAttributionPathSpec.OWNER`). */
+export declare const OWNER_PATH_PREFIX = "/owner/{ownerId}";
+/**
+ * The resource attribution a query client of an aggregate uses, as the
+ * `ResourceAttributionPathSpec` member it generates: the prefix most of the
+ * aggregate's command routes start with, owner on a tie, none when no route
+ * starts with either.
+ *
+ * @example
+ * ```typescript
+ * // commands at /tenant/{tenantId}/users, /tenant/{tenantId}/orders and /owner/{ownerId}/profile
+ * inferPathSpecType(aggregate); // 'ResourceAttributionPathSpec.TENANT'
+ * ```
+ */
+export declare function inferPathSpecType(aggregateDefinition: Pick<AggregateDefinition, 'commands'>): string;

package/dist/wow/model.d.cts

@@ -0,0 +1,116 @@
+import { HTTPMethod, Operation, Parameter, Tag } from '@ahoo-wang/fetcher-openapi';
+import { AliasAggregate, Named } from '@ahoo-wang/wow-client';
+import { KeySchema } from '../openapi/components.cjs';
+export interface CommandDefinition extends Named {
+    /**
+     * The name of the command
+     */
+    name: string;
+    /**
+     * The HTTP method for the command
+     */
+    method: HTTPMethod;
+    /**
+     * The endpoint path for the command
+     */
+    path: string;
+    /**
+     * The path parameters for the command
+     */
+    pathParameters: Parameter[];
+    summary?: string;
+    description?: string;
+    /**
+     * The schema for the command body
+     */
+    schema: KeySchema;
+    operation: Operation;
+}
+export interface EventDefinition extends Named {
+    /**
+     * The name of the event
+     */
+    name: string;
+    /**
+     * The title of the event
+     */
+    title: string;
+    /**
+     * The schema for the event body
+     */
+    schema: KeySchema;
+}
+export interface TagAliasAggregate extends AliasAggregate {
+    tag: Tag;
+}
+/**
+ * Complete definition of an aggregate including its commands, events, and state schemas.
+ */
+export interface AggregateDefinition {
+    /** The aggregate metadata with tag and alias information */
+    aggregate: TagAliasAggregate;
+    /**
+     * The aggregate's route segment, which is its name unless the aggregate
+     * sets a resource name: `sales-order` for the aggregate `order`.
+     */
+    resourceName: string;
+    /**
+     * The schema for the aggregate root state
+     */
+    state: KeySchema;
+    /**
+     * The fields schema for aggregate queries
+     */
+    fields: KeySchema;
+    /**
+     * Map of command names to command definitions
+     */
+    commands: Map<string, CommandDefinition>;
+    /**
+     * Map of event names to event definitions
+     */
+    events: Map<string, EventDefinition>;
+}
+/**
+ * Map of context aliases to sets of aggregate definitions
+ */
+export type BoundedContextAggregates = Map<string, Set<AggregateDefinition>>;
+/**
+ * The doc comment the Wow metadata lends a schema: a command body takes its
+ * operation's summary and description where it has none of its own, an event
+ * body the title of its domain event. It holds every field the metadata
+ * sets, in the order it sets them, so a model's doc reads the schema with
+ * these over it the way it read the document the old resolver changed in
+ * place: a field the schema lacks comes last, and an `undefined` one is left
+ * out. The document itself is never changed.
+ */
+export type SchemaDocOverride = Readonly<Partial<Record<'title' | 'description', string | undefined>>>;
+/** What the Wow metadata of a document says, read without changing it. */
+export interface WowModel {
+    /** The bounded context the document names (`info.x-wow-context-alias`). */
+    readonly contextAlias?: string;
+    /** The aggregates that have state and query fields, by context alias. */
+    readonly contexts: BoundedContextAggregates;
+    /**
+     * The tags of every aggregate that exposes a Wow route, resolved or not.
+     * Their operations belong to command and query clients, not to API clients.
+     */
+    readonly aggregateTags: ReadonlySet<string>;
+    /** The doc comments the metadata lends schemas, by component key. */
+    readonly schemaDocOverrides: ReadonlyMap<string, SchemaDocOverride>;
+    /** Aggregates and commands skipped for missing metadata, a warning each. */
+    readonly warnings: readonly string[];
+}
+/**
+ * Tells whether the document comes from a Wow service: it names its bounded
+ * context, or it has aggregates.
+ */
+export declare function isWowDocument(wow: Pick<WowModel, 'contextAlias' | 'aggregateTags'>): boolean;
+/**
+ * A schema as a model's doc reads it: the schema with the doc comment the
+ * Wow metadata lends it over it.
+ *
+ * @param schema - The schema, left unchanged
+ * @param override - What the metadata lends it, if anything
+ */
+export declare function withDocOverride<T extends object>(schema: T, override: SchemaDocOverride | undefined): T;

package/dist/wow/model.d.ts

@@ -0,0 +1,116 @@
+import { HTTPMethod, Operation, Parameter, Tag } from '@ahoo-wang/fetcher-openapi';
+import { AliasAggregate, Named } from '@ahoo-wang/wow-client';
+import { KeySchema } from '../openapi/components.js';
+export interface CommandDefinition extends Named {
+    /**
+     * The name of the command
+     */
+    name: string;
+    /**
+     * The HTTP method for the command
+     */
+    method: HTTPMethod;
+    /**
+     * The endpoint path for the command
+     */
+    path: string;
+    /**
+     * The path parameters for the command
+     */
+    pathParameters: Parameter[];
+    summary?: string;
+    description?: string;
+    /**
+     * The schema for the command body
+     */
+    schema: KeySchema;
+    operation: Operation;
+}
+export interface EventDefinition extends Named {
+    /**
+     * The name of the event
+     */
+    name: string;
+    /**
+     * The title of the event
+     */
+    title: string;
+    /**
+     * The schema for the event body
+     */
+    schema: KeySchema;
+}
+export interface TagAliasAggregate extends AliasAggregate {
+    tag: Tag;
+}
+/**
+ * Complete definition of an aggregate including its commands, events, and state schemas.
+ */
+export interface AggregateDefinition {
+    /** The aggregate metadata with tag and alias information */
+    aggregate: TagAliasAggregate;
+    /**
+     * The aggregate's route segment, which is its name unless the aggregate
+     * sets a resource name: `sales-order` for the aggregate `order`.
+     */
+    resourceName: string;
+    /**
+     * The schema for the aggregate root state
+     */
+    state: KeySchema;
+    /**
+     * The fields schema for aggregate queries
+     */
+    fields: KeySchema;
+    /**
+     * Map of command names to command definitions
+     */
+    commands: Map<string, CommandDefinition>;
+    /**
+     * Map of event names to event definitions
+     */
+    events: Map<string, EventDefinition>;
+}
+/**
+ * Map of context aliases to sets of aggregate definitions
+ */
+export type BoundedContextAggregates = Map<string, Set<AggregateDefinition>>;
+/**
+ * The doc comment the Wow metadata lends a schema: a command body takes its
+ * operation's summary and description where it has none of its own, an event
+ * body the title of its domain event. It holds every field the metadata
+ * sets, in the order it sets them, so a model's doc reads the schema with
+ * these over it the way it read the document the old resolver changed in
+ * place: a field the schema lacks comes last, and an `undefined` one is left
+ * out. The document itself is never changed.
+ */
+export type SchemaDocOverride = Readonly<Partial<Record<'title' | 'description', string | undefined>>>;
+/** What the Wow metadata of a document says, read without changing it. */
+export interface WowModel {
+    /** The bounded context the document names (`info.x-wow-context-alias`). */
+    readonly contextAlias?: string;
+    /** The aggregates that have state and query fields, by context alias. */
+    readonly contexts: BoundedContextAggregates;
+    /**
+     * The tags of every aggregate that exposes a Wow route, resolved or not.
+     * Their operations belong to command and query clients, not to API clients.
+     */
+    readonly aggregateTags: ReadonlySet<string>;
+    /** The doc comments the metadata lends schemas, by component key. */
+    readonly schemaDocOverrides: ReadonlyMap<string, SchemaDocOverride>;
+    /** Aggregates and commands skipped for missing metadata, a warning each. */
+    readonly warnings: readonly string[];
+}
+/**
+ * Tells whether the document comes from a Wow service: it names its bounded
+ * context, or it has aggregates.
+ */
+export declare function isWowDocument(wow: Pick<WowModel, 'contextAlias' | 'aggregateTags'>): boolean;
+/**
+ * A schema as a model's doc reads it: the schema with the doc comment the
+ * Wow metadata lends it over it.
+ *
+ * @param schema - The schema, left unchanged
+ * @param override - What the metadata lends it, if anything
+ */
+export declare function withDocOverride<T extends object>(schema: T, override: SchemaDocOverride | undefined): T;

package/dist/wow/resolveWowModel.d.cts

@@ -0,0 +1,21 @@
+import { OpenApiDocument } from '../openapi/document.cjs';
+import { WowModel } from './model.cjs';
+/**
+ * Reads the Wow metadata of a document: its bounded context, and each
+ * aggregate its tags name with the aggregate's commands, events, state,
+ * query fields and route segment.
+ *
+ * An aggregate needs its state (`snapshot_state.single`) and its query fields
+ * (`snapshot.count`) to generate clients; one that lacks either is left out
+ * with a warning, and so is a command whose body is not a component schema.
+ *
+ * It is a pure function: the document is left as it was. The doc comments the
+ * metadata lends command and event bodies are in
+ * {@link WowModel.schemaDocOverrides}.
+ *
+ * @param document - The document
+ * @returns The Wow model, and the warnings to log
+ * @throws GeneratorError (`specification`) when an aggregate's Wow metadata
+ * is malformed, or a command's response references form a cycle
+ */
+export declare function resolveWowModel(document: OpenApiDocument): WowModel;

package/dist/wow/resolveWowModel.d.ts

@@ -0,0 +1,21 @@
+import { OpenApiDocument } from '../openapi/document.js';
+import { WowModel } from './model.js';
+/**
+ * Reads the Wow metadata of a document: its bounded context, and each
+ * aggregate its tags name with the aggregate's commands, events, state,
+ * query fields and route segment.
+ *
+ * An aggregate needs its state (`snapshot_state.single`) and its query fields
+ * (`snapshot.count`) to generate clients; one that lacks either is left out
+ * with a warning, and so is a command whose body is not a component schema.
+ *
+ * It is a pure function: the document is left as it was. The doc comments the
+ * metadata lends command and event bodies are in
+ * {@link WowModel.schemaDocOverrides}.
+ *
+ * @param document - The document
+ * @returns The Wow model, and the warnings to log
+ * @throws GeneratorError (`specification`) when an aggregate's Wow metadata
+ * is malformed, or a command's response references form a cycle
+ */
+export declare function resolveWowModel(document: OpenApiDocument): WowModel;

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@ahoo-wang/wow-generator",
+  "version": "9.2.0-rc.0",
+  "description": "Generates TypeScript models, Fetcher decorator clients and Wow command and query clients from a local or remote OpenAPI 3 document. The Wow clients follow the CQRS model of the Wow DDD framework (https://github.com/Ahoo-Wang/Wow).",
+  "keywords": [
+    "wow",
+    "wow-generator",
+    "cqrs",
+    "ddd",
+    "openapi",
+    "openapi3",
+    "swagger",
+    "generator",
+    "codegen",
+    "typescript",
+    "api",
+    "client",
+    "rest",
+    "fetch",
+    "http"
+  ],
+  "author": "Ahoo-Wang",
+  "license": "Apache-2.0",
+  "homepage": "https://wow.ahoo.me/reference/typescript/wow-generator/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ahoo-Wang/Wow.git",
+    "directory": "typescript/wow-generator"
+  },
+  "bugs": {
+    "url": "https://github.com/Ahoo-Wang/Wow/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "wow-generator": "./dist/cli.js",
+    "fetcher-generator": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@ahoo-wang/fetcher": "^5.1.5",
+    "@ahoo-wang/fetcher-decorator": "^5.1.5",
+    "@ahoo-wang/fetcher-eventstream": "^5.1.5",
+    "@ahoo-wang/wow-client": "~9.2.0-rc.0"
+  },
+  "dependencies": {
+    "ts-morph": "^28.0.0",
+    "commander": "^14.0.3",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@ahoo-wang/fetcher": "^5.1.5",
+    "@ahoo-wang/fetcher-decorator": "^5.1.5",
+    "@ahoo-wang/fetcher-eventstream": "^5.1.5",
+    "@ahoo-wang/fetcher-openapi": "^5.1.5",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.3",
+    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/ui": "^4.1.11",
+    "eslint": "^10.11.0",
+    "eslint-plugin-import-x": "^4.17.1",
+    "globals": "^17.12.0",
+    "prettier": "3.9.9",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.70.1",
+    "unplugin-dts": "1.1.1",
+    "vite": "8.3.1",
+    "vite-bundle-analyzer": "^1.3.9",
+    "vitest": "^4.1.11",
+    "@ahoo-wang/wow-client": "~9.2.0-rc.0"
+  },
+  "scripts": {
+    "build": "vite build && pnpm test:package",
+    "test:package": "node scripts/verify-package.mjs",
+    "test:ui": "vitest --ui",
+    "test": "vitest run --coverage --testTimeout=15000 && pnpm test:type",
+    "test:type": "tsc --noEmit -p test/tsconfig.types.json",
+    "lint": "eslint . --fix",
+    "clean": "rm -rf dist",
+    "analyze": "npx vite-bundle-analyzer -p auto",
+    "generate": "node dist/cli.js generate -i test/demo.spec.json -o test-output -t tsconfig.json",
+    "test:no-coverage": "vitest run --coverage.enabled=false --testTimeout=15000 && pnpm test:type",
+    "bench": "node scripts/bench.mjs"
+  }
+}