@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

package/dist/client/generateDirectClient.js

@@ -1,14 +1,17 @@
 import { directLimit } from '../compiler/directExecutionPolicy.js';
-import { DIRECT_CLIENT_RUNTIME_VERSION, DIRECT_CLIENT_RUNTIME_REPAIR } from './directClientVersion.js';
-/** Internal native-plan generator. Deliberately absent from index.ts and the CLI. */
+import { DIRECT_CLIENT_RUNTIME_VERSION, DIRECT_CLIENT_RUNTIME_REPAIR, COMPONENT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_REPAIR } from './directClientVersion.js';
+/** Native-plan generator consumed by the opt-in checked pipeline. */
 import { checkSemanticBudget } from '../compiler/semanticBudget.js';
-import { writeFileSync } from 'node:fs';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
 import { inspectDirectOperation } from '../compiler/directOperation.js';
-import { inspectDirectValueMapping } from '../compiler/directValues.js';
-import { checkDirectSourceCompatibility, createDirectSourceCapsule } from '../compiler/directSourceCapsule.js';
+import { inspectDirectValueMapping, inspectComponentValueMapping } from '../compiler/directValues.js';
+import { checkDirectSourceCompatibility, createDirectSourceCapsule, componentSourceCapsuleBytes, inspectReconstructedComponentSource, inspectComponentSourceService } from '../compiler/directSourceCapsule.js';
+import { lowerComponentShape } from '../generation/componentShape.js';
 import { composeGeneratedSource, resolvePreamble } from '../generation/preamble.js';
 const MAX_SOURCE_BYTES = 512 * 1024;
 const generatedArtifacts = new WeakMap();
+const componentArtifactOwners = new WeakMap();
 /** Roles are separate declarations, so equal local names never merge namespace identities. */
 export function generateDirectClient(expected, signal) {
     const { budget } = inspectDirectOperation(expected.contract).context;
@@ -67,7 +70,7 @@ export function generateDirectClient(expected, signal) {
         const faults = mappings.filter(m => m.direction.kind === 'fault');
         const lines = [
             '// Checked direct client; inject checkedDirectRuntimeV1 from the package root.',
-            '// Generation remains internal; this unreleased binding supports only the documented direct grammar.',
+            '// Opt-in preview binding supports only the documented direct grammar.',
             '// Static number types require native int32 validation; native checks enforce exact shapes.',
             `export type Request = ${shape(input)};`,
             `export type Response = ${shape(output)};`,
@@ -97,6 +100,7 @@ export function generateDirectClient(expected, signal) {
             }).join(' | ') : 'never') + ';',
             'export type Result = Failure | (Common & { readonly kind: "soap-response"; readonly value: Response }) | DeclaredFault;',
             `const capsule = ${literal(Buffer.from(capsule.bytes).toString('base64'))};`,
+            'export const expectedCapsuleBase64 = capsule;',
             `export const selection = ${literal(JSON.stringify({ selector: expected.contract.selector, ...expected.selection }))};`,
             'export function createClient(runtime: Runtime) {',
             '  return Object.freeze({',
@@ -134,3 +138,131 @@ export function writeDirectClient(file, generated) {
     checkSemanticBudget(budget);
     writeFileSync(file, generated.source, 'utf8');
 }
+/** Emit recursive component types and the existing checked runtime injection protocol.
+ * @remarks Native reconstruction and mappings remain authoritative; generated TypeScript is a static description.
+ * @returns An authentic writable artifact, or explicit refusal. No legacy catalog or saved report is consumed.
+ * @throws TypeError For copied/foreign reconstruction handles. Caller cancellation returns a refusal.
+ */
+export async function generateComponentClient(expected, signal) {
+    inspectReconstructedComponentSource(expected);
+    const { budget } = inspectDirectOperation(expected.contract).context;
+    const failure = (kind, rule) => ({ kind, rule,
+        repair: COMPONENT_CLIENT_RUNTIME_REPAIR, usage: Object.freeze({ ...budget.usage() }) });
+    const check = () => { checkSemanticBudget(budget); if (signal?.aborted)
+        throw new Error('cancelled'); };
+    try {
+        check();
+        const capsule = { bytes: componentSourceCapsuleBytes(expected, signal) };
+        const literal = (value) => JSON.stringify(value).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+        const mappings = expected.mappings;
+        const input = mappings.find(mapping => mapping.direction.kind === 'input');
+        const output = mappings.find(mapping => mapping.direction.kind === 'output');
+        const request = lowerComponentShape(expected.contract, input, 'Request', check);
+        const response = lowerComponentShape(expected.contract, output, 'Response', check);
+        const faults = mappings.filter(mapping => mapping.direction.kind === 'fault').map((mapping, index) => ({ mapping,
+            shape: lowerComponentShape(expected.contract, mapping, `Fault_${index}`, check) }));
+        const grouped = mappings.some(mapping => mapping.kind === 'component-mapping'
+            && inspectComponentValueMapping(mapping, expected.contract).applicationGroups);
+        const declarations = grouped ? [...new Set([...request.declarations, ...response.declarations, ...faults.flatMap(({ shape }) => shape.declarations)]),
+            `export type Request = ${request.type};`, `export type Response = ${response.type};`,
+            ...faults.map(({ shape }, index) => `export type Fault_${index} = ${shape.type};`)] : [
+            ...request.declarations, `export type Request = ${request.type};`,
+            ...response.declarations, `export type Response = ${response.type};`,
+            ...faults.flatMap(({ shape }, index) => [...shape.declarations, `export type Fault_${index} = ${shape.type};`])
+        ];
+        const lines = [
+            '// Checked component client; inject checkedComponentRuntimeV1 from the package root.',
+            '// Scalar facets, ordered occurrence correlation and wildcard membership remain native runtime duties.',
+            ...declarations,
+            'export interface Usage {readonly nodes: number; readonly work: number}',
+            'export interface Name {readonly namespace: string; readonly local: string}',
+            'export interface Options {',
+            '  readonly localSource: string; readonly fileRoots: readonly string[]; readonly capsule: Uint8Array;',
+            '  readonly sourceResources: readonly {readonly uri: string; readonly file: string; readonly canonicalUri?: string}[]; readonly sourceOrigins: readonly string[];',
+            '  readonly sourceUri?: string;',
+            '  readonly namespaceLocations?: readonly {readonly namespace: string; readonly location: string}[];',
+            '  readonly standardLibraries?: readonly string[];',
+            '  readonly recordSources?: readonly {readonly selector: {readonly portType: Name; readonly binding: Name; readonly operation: string}; readonly source: string}[];',
+            '  readonly soap: {readonly service: Name; readonly port: string; readonly endpoint?: string;',
+            '    readonly allowEndpoint?: (endpoint: URL) => boolean; readonly signal?: AbortSignal; readonly timeoutMs?: number;',
+            '    readonly capabilities?: readonly string[]; readonly ca?: string;',
+            '    readonly limits?: {readonly maxBytes?: number; readonly maxDepth?: number; readonly maxNodes?: number; readonly maxText?: number}};',
+            '}',
+            'export interface Failure {readonly kind: "incompatible-artifact" | "unsupported" | "missing-authority" | "resource-limit" | "cancelled" | "inconclusive" | "invalid-schema" | "scalar-invalid" | "value-invalid" | "xml-invalid" | "mismatch" | "transport" | "protocol";',
+            '  readonly rule: string; readonly repair?: string; readonly phase?: "input" | "response"; readonly usage: Usage}',
+            'export interface NativeSuccess {readonly kind: "soap-response" | "soap-fault"; readonly value: unknown; readonly admitted: false;',
+            '  readonly status: number; readonly usage: Usage; readonly responseBytes: Uint8Array;',
+            '  readonly fault?: {readonly name: string; readonly code: Name; readonly string: string; readonly actor?: string}}',
+            `export interface Runtime {readonly version: ${literal(COMPONENT_CLIENT_RUNTIME_VERSION)}; execute(expectedBase64: string, input: unknown, options: Options, version: ${literal(COMPONENT_CLIENT_RUNTIME_VERSION)}): Promise<Failure | NativeSuccess>}`,
+            'type Common = {readonly admitted: false; readonly status: number; readonly usage: Usage; readonly responseBytes: Uint8Array};',
+            'export type Result = Failure | (Common & {readonly kind: "soap-response"; readonly value: Response})',
+            ...faults.map(({ mapping }, index) => {
+                if (mapping.direction.kind !== 'fault')
+                    throw new TypeError('Native fault mapping required');
+                return `  | (Common & {readonly kind: "soap-fault"; readonly value: Fault_${index}; readonly fault: {readonly name: ${literal(mapping.direction.name)}; readonly code: Name; readonly string: string; readonly actor?: string}})`;
+            }),
+            ...(faults.length ? [] : ['  | (Common & {readonly kind: "soap-fault"; readonly value: never; readonly fault: {readonly name: never; readonly code: Name; readonly string: string; readonly actor?: string}})']),
+            ';',
+            `export const expectedCapsuleBase64 = ${literal(Buffer.from(capsule.bytes).toString('base64'))};`,
+            `export const selection = ${literal(JSON.stringify({ selector: expected.contract.selector, ...expected.selection }))};`,
+            'export function createClient(runtime: Runtime) {',
+            '  return Object.freeze({',
+            `    [${literal(expected.contract.selector.operation)}]: async (input: Request, options: Options): Promise<Result> => {`,
+            `      if (runtime.version !== ${literal(COMPONENT_CLIENT_RUNTIME_VERSION)}) return {kind: "incompatible-artifact", rule: "generated-runtime-version", repair: ${literal(COMPONENT_CLIENT_RUNTIME_REPAIR)}, usage: {nodes: 0, work: 0}};`,
+            `      return await runtime.execute(expectedCapsuleBase64, input, options, ${literal(COMPONENT_CLIENT_RUNTIME_VERSION)}) as Result;`,
+            '    },', '  });', '}', '',
+        ];
+        const source = composeGeneratedSource(lines.join('\n'), resolvePreamble('direct-client'));
+        if (Buffer.byteLength(source) > directLimit(budget, MAX_SOURCE_BYTES))
+            return failure('resource-limit', 'generated-source-byte-limit');
+        check();
+        const artifact = Object.freeze({ kind: 'generated-component-client', source, capsule: capsule.bytes,
+            admitted: false, usage: Object.freeze({ ...budget.usage() }) });
+        generatedArtifacts.set(artifact, budget);
+        componentArtifactOwners.set(artifact, expected);
+        return artifact;
+    }
+    catch (error) {
+        if (budget.exhausted())
+            return failure('resource-limit', 'request-budget');
+        if (signal?.aborted)
+            return failure('cancelled', 'cooperative-cancellation');
+        throw error;
+    }
+}
+/** Emit a service client index and per-operation native artifacts using the existing component emitter.
+ * @remarks All operation artifacts are prepared before writing. The index contains no source authority.
+ * @returns Generator-owned relative capsule paths, keyed by exact operation name.
+ * @throws For foreign/mixed native operations, refused generation, cancellation or filesystem failure.
+ */
+export async function writeComponentServiceClient(expected, directory, signal, prepared) {
+    const operations = inspectComponentSourceService(expected);
+    const generated = [];
+    if (prepared && prepared.length !== operations.length)
+        throw new TypeError('Prepared operation artifacts must match the service');
+    for (const [index, operation] of operations.entries()) {
+        const artifact = prepared?.[index] ?? await generateComponentClient(operation, signal);
+        if (artifact.kind !== 'generated-component-client')
+            throw new Error(`Checked client refused: ${artifact.kind}: ${artifact.rule}`);
+        if (componentArtifactOwners.get(artifact) !== operation)
+            throw new TypeError('Prepared client belongs to another native operation');
+        generated.push(artifact);
+    }
+    const files = Object.create(null);
+    const lines = operations.flatMap((_, index) => [
+        `import {createClient as operation_${index}} from './operations/${index}/client.js';`,
+        `export * as Operation_${index} from './operations/${index}/client.js';`,
+    ]);
+    lines.push("import type {Runtime, Options as OperationOptions} from './operations/0/client.js';", "export type Options = Omit<OperationOptions, 'capsule'>;", `export const selection = ${JSON.stringify(JSON.stringify(operations[0].selection))};`, 'export function createClient(runtime: Runtime) {', '  return Object.freeze({', ...operations.map((_, index) => `    ...operation_${index}(runtime),`), '  });', '}', '');
+    for (const [index, operation] of operations.entries()) {
+        const dir = path.join(directory, 'operations', String(index));
+        mkdirSync(dir, { recursive: true });
+        writeDirectClient(path.join(dir, 'client.ts'), generated[index]);
+        writeFileSync(path.join(dir, 'contract.json'), generated[index].capsule);
+        files[operation.contract.selector.operation] = `operations/${index}/contract.json`;
+    }
+    const { budget } = inspectDirectOperation(operations[0].contract).context;
+    checkSemanticBudget(budget);
+    writeFileSync(path.join(directory, 'client.ts'), composeGeneratedSource(lines.join('\n'), resolvePreamble('direct-client')), 'utf8');
+    return Object.freeze(files);
+}

package/dist/client/generateOperations.d.ts

@@ -11,4 +11,3 @@ import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
  * @throws {Error} If a packaged preamble cannot be loaded or the TypeScript file cannot be written.
  */
 export declare function generateOperations(outFile: string, compiled: CompiledCatalog): void;
-//# sourceMappingURL=generateOperations.d.ts.map

package/dist/client/generateOperations.js

@@ -4,6 +4,7 @@
  * Generates a fully-typed operations interface for the SOAP client.
  * This standalone interface enables mocking and testing without importing
  * the concrete SOAP client class or its runtime dependencies.
+ * @since Unreleased
  */
 import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import { deriveClientName, pascal } from "../util/tools.js";
@@ -31,18 +32,25 @@ export function generateOperations(outFile, compiled) {
         .map(line => line.replace(/\*\//g, "*\\/"));
     // Collect type names used in method signatures for the import statement
     const importedTypes = new Set();
+    const operationTypes = compiled.operations.map(operation => ({ operation,
+        input: operation.inputTypeName ?? (operation.inputElement ? pascal(operation.inputElement.local) : undefined),
+        output: operation.outputTypeName ?? (operation.outputElement ? pascal(operation.outputElement.local) : undefined),
+    }));
+    const reservedTypes = new Set(["Promise", "AsyncIterable", "AbortSignal", "StreamCallOptions", "StreamOperationResponse", `${clientName}Operations`]);
+    // @constraints Qualify model references when their public names overlap generated helpers or native transport types.
+    const namespaceModels = operationTypes.some(({ operation, input, output }) => [input, output, operation.stream?.recordTypeName].some(name => name !== undefined && reservedTypes.has(name)));
+    const modelType = (name) => namespaceModels ? `T.${name}` : name;
     const methods = [];
     // Does any operation opt into streaming? If so we also emit the
     // StreamOperationResponse helper type below.
     let anyStream = false;
-    for (const op of compiled.operations) {
-        const inTypeName = op.inputTypeName ?? (op.inputElement ? pascal(op.inputElement.local) : undefined);
-        const outTypeName = op.outputTypeName ?? (op.outputElement ? pascal(op.outputElement.local) : undefined);
+    for (const { operation: op, input: inTypeName, output: outTypeName } of operationTypes) {
         if (!inTypeName && !outTypeName) {
             continue;
         }
-        const inTs = inTypeName ?? "Record<string, unknown>";
-        const outTs = outTypeName ?? "unknown";
+        // @constraints WSDL DTOs may be named Record and shadow the built-in utility type.
+        const inTs = inTypeName ? modelType(inTypeName) : "{[key: string]: unknown}";
+        const outTs = outTypeName ? modelType(outTypeName) : "unknown";
         if (inTypeName)
             importedTypes.add(inTypeName);
         if (outTypeName)
@@ -56,8 +64,9 @@ export function generateOperations(outFile, compiled) {
             const recordTs = op.stream.recordTypeName;
             importedTypes.add(recordTs);
             methods.push(`${docBlock}  ${op.name}(\n` +
-                `    args: ${inTs}\n` +
-                `  ): Promise<StreamOperationResponse<${recordTs}>>;\n`);
+                `    args: ${inTs},\n` +
+                `    options?: StreamCallOptions\n` +
+                `  ): Promise<StreamOperationResponse<${modelType(recordTs)}>>;\n`);
         }
         else {
             methods.push(`${docBlock}  ${op.name}(\n` +
@@ -68,16 +77,26 @@ export function generateOperations(outFile, compiled) {
     // Build sorted import list for deterministic output
     const sortedImports = Array.from(importedTypes).sort();
     const typeImport = sortedImports.length > 0
-        ? `import type {\n${sortedImports.map((t) => `  ${t},`).join("\n")}\n} from "./types${suffix}";\n\n`
+        ? namespaceModels
+            ? `import type * as T from "./types${suffix}";\n\n`
+            : `import type {\n${sortedImports.map((t) => `  ${t},`).join("\n")}\n} from "./types${suffix}";\n\n`
         : "";
     // Emit the StreamOperationResponse helper type iff at least one operation
     // is stream-configured. Kept inside operations.ts so that mocks and gateway
     // code can import it without pulling in the SOAP runtime. The raw template
     // lives in a sibling .tpl file so the IDE does not try to parse embedded
-    // TypeScript type-parameter defaults (HeadersType = Record<...>) as
-    // JavaScript assignment expressions.
+    // TypeScript generic defaults as JavaScript assignment expressions.
     const streamHelper = anyStream
-        ? loadRuntimeSource("operationsStreamHelper.tpl.txt").replace(/__CLIENT_NAME__/g, clientName)
+        ? `/**
+ * Per-call stream cancellation and total request/response deadline.
+ * @since Unreleased
+ */
+export interface StreamCallOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+` + loadRuntimeSource("operationsStreamHelper.tpl.txt").replace(/__CLIENT_NAME__/g, clientName)
         : "";
     const content = `/**
  * Typed operations interface for the ${clientName} service.

package/dist/client/generateTypes.d.ts

@@ -20,4 +20,3 @@ import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
  * @throws {Error} If a packaged preamble cannot be loaded or the TypeScript file cannot be written.
  */
 export declare function generateTypes(outFile: string, compiled: CompiledCatalog): void;
-//# sourceMappingURL=generateTypes.d.ts.map

package/dist/client/generateUtils.d.ts

@@ -19,4 +19,3 @@ import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
  * @throws {Error} If a packaged preamble cannot be loaded or the TypeScript file cannot be written.
  */
 export declare function generateUtils(outFile: string, compiled: CompiledCatalog): void;
-//# sourceMappingURL=generateUtils.d.ts.map

package/dist/client/generateUtils.js

@@ -48,7 +48,9 @@ export function generateUtils(outFile, compiled) {
             return max === "unbounded" || (typeof max === "number" && max > 1);
         }).sort(),
     ]));
-    const metas = JSON.stringify({ Attributes: attrSpec, ChildrenTypes: childType, RepeatedElements: repeatedElements }, null, 2);
+    const metas = JSON.stringify({ Attributes: attrSpec, AttributeTypes: compiled.meta.attrType ?? {}, ChildrenTypes: childType, RepeatedElements: repeatedElements,
+        NonNillableElements: Object.fromEntries(Object.entries(compiled.meta.propMeta ?? {}).sort(([a], [b]) => a.localeCompare(b))
+            .map(([name, properties]) => [name, Object.keys(properties).filter(key => properties[key].nillable === false).sort()])) }, null, 2);
     const dataTypes = `/**
  * ${clientName} WSDL data types for proper serialization/deserialization.
  * Used to distinguish between XML attributes and elements during conversion.
@@ -56,10 +58,14 @@ export function generateUtils(outFile, compiled) {
 export interface ${clientName}DataTypes {
   /** Maps type names to lists of property names that should be treated as XML attributes */
   Attributes: Record<string, readonly string[]>;
+  /** Maps attributes to their projected scalar types for XML response conversion. */
+  AttributeTypes?: Record<string, Readonly<Record<string, string>>>;
   /** Maps type names to their child element types for recursive processing */
   ChildrenTypes: Record<string, Readonly<Record<string, string>>>;
   /** Maps type names to repeated child properties; optional for custom metadata compatibility. */
   RepeatedElements?: Record<string, readonly string[]>;
+  /** Distinguishes empty complex nodes collapsed to null by node-soap from declared nullable children. */
+  NonNillableElements?: Record<string, readonly string[]>;
 }
 
 export const ${clientConstant}_DATA_TYPES: ${clientName}DataTypes = ${metas} as const;\n`;

package/dist/compiler/applicationGroups.d.ts

@@ -0,0 +1,53 @@
+import type { SemanticContext } from './semanticContext.js';
+import type { SemanticParticle } from './particleSemanticView.js';
+import type { DirectProjectionPlan, DirectProjectionSlot } from './directStructurePlan.js';
+export interface ApplicationGroupName {
+    readonly target: string;
+    readonly propertyName?: string;
+    readonly typeName?: string;
+}
+export interface ApplicationGroupsOptions {
+    readonly names?: readonly ApplicationGroupName[];
+}
+export interface ApplicationGroupTarget {
+    readonly target: string;
+    readonly role: 'choice' | 'sequence' | 'alternative';
+    readonly source: string;
+    readonly defaults: {
+        readonly propertyName?: string;
+        readonly typeName: string;
+    };
+    readonly resolved: {
+        readonly propertyName?: string;
+        readonly typeName: string;
+    };
+}
+export interface ApplicationGroupRecord {
+    readonly source: string;
+    readonly disposition: 'grouped' | 'retained-ordered' | 'compact';
+    readonly reason: string;
+}
+export type GroupNode = {
+    readonly particle: SemanticParticle;
+    readonly slot?: DirectProjectionSlot;
+    readonly children: readonly GroupNode[];
+    readonly target?: ApplicationGroupTarget;
+    readonly alternatives?: readonly ApplicationGroupTarget[];
+};
+export interface ApplicationGroupPlan {
+    readonly records: Readonly<Record<string, GroupNode>>;
+    readonly targets: readonly ApplicationGroupTarget[];
+    readonly dispositions: readonly ApplicationGroupRecord[];
+}
+/** Stable private record symbol shared across operation directions and schema scopes. */
+export declare const applicationRecordName: (id: string) => string;
+/** Copy strict data-only generation options, rejecting malformed arrays before any source work. */
+export declare function parseApplicationGroups(value: unknown): ApplicationGroupsOptions;
+/** Derive finite group definitions from exact qualified records; no caller inventory is trusted. */
+export declare function planApplicationGroups(context: SemanticContext, projection: DirectProjectionPlan, options: ApplicationGroupsOptions, checkpoint: () => void): ApplicationGroupPlan;
+export declare class ApplicationGroupValueError extends Error {
+}
+/** Convert owned data between grouped and existing ordered values without adding XML wrappers.
+ * @constraints Input must first pass the bounded data-only owner; recursive calls are depth-limited.
+ */
+export declare function mapApplicationGroups(plan: ApplicationGroupPlan, projection: DirectProjectionPlan, input: unknown, direction: 'to-native' | 'from-native', check: () => void): unknown;