@techspokes/typescript-wsdl-client 1.1.3 → 1.1.4

package/README.md

@@ -228,6 +228,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Production Guide](docs/production.md) | CI/CD, validation, logging |
 | [Troubleshooting](docs/troubleshooting.md) | Common issues and debugging |
 | [Release Notes](docs/releases/README.md) | Per-version GitHub release notes used by the draft release workflow |
+| [v1.1.4 Release Notes](docs/releases/v1.1.4.md) | Named SOAP imports and compiled-client coverage on Node 24 and 26 |
 | [v1.1.3 Release Notes](docs/releases/v1.1.3.md) | Dependency security updates and Node 24 development alignment |
 | [v1.1.2 Release Notes](docs/releases/v1.1.2.md) | Sequence occurrence bounds and singleton SOAP response normalization |
 | [v1.1.1 Release Notes](docs/releases/v1.1.1.md) | Wrapping sequence occurrence bounds and generated array contracts |

package/dist/client/generateClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateClient.d.ts","sourceRoot":"","sources":["../../src/client/generateClient.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAKnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAkaxE"}
+{"version":3,"file":"generateClient.d.ts","sourceRoot":"","sources":["../../src/client/generateClient.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAKnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QA+axE"}

package/dist/client/generateClient.js

@@ -56,6 +56,16 @@ export function generateClient(outFile, compiled) {
     // get the class name for the client
     const clientName = deriveClientName(compiled);
     const clientConstant = pascalToSnakeCase(clientName).toUpperCase();
+    // Explicit client-name overrides can match a SOAP export. Alias only that
+    // import so the generated class keeps its public name.
+    const soapImport = (name) => {
+        const local = name === clientName ? `Soap${pascal(name)}` : name;
+        return { local, specifier: local === name ? name : `${name} as ${local}` };
+    };
+    const soapClient = soapImport("Client");
+    const soapOptions = soapImport("IOptions");
+    const soapSecurity = soapImport("ISecurity");
+    const soapFactory = soapImport("createClientAsync");
     // Track whether any operation opts into streaming, so we can emit the
     // supporting runtime helpers only when they're actually used.
     let anyStream = false;
@@ -133,7 +143,9 @@ export function generateClient(outFile, compiled) {
     // *.tpl file so the IDE does not try to parse their content as code nested
     // inside this template literal (which would flag `this`, `await`, `yield`
     // outside-of-function false positives).
-    const streamMethodsBlock = anyStream ? "\n" + loadRuntimeSource("clientStreamMethods.tpl.txt") : "";
+    const streamMethodsBlock = anyStream
+        ? "\n" + loadRuntimeSource("clientStreamMethods.tpl.txt").replace("__SOAP_CLIENT_TYPE__", soapClient.local)
+        : "";
     // noinspection JSFileReferences,JSUnresolvedReference,CommaExpressionJS,JSDuplicatedDeclaration,ReservedWordAsName,JSCommentMatchesSignature,JSValidateTypes,JSIgnoredPromiseFromCall,BadExpressionStatementJS,ES6UnusedImports,JSUnnecessarySemicolon,UnreachableCodeJS,JSUnusedLocalSymbols
     const classTemplate = `// noinspection JSAnnotator
 
@@ -141,7 +153,8 @@ export function generateClient(outFile, compiled) {
  * Generated ${clientName} client class.
  * This class wraps the node-soap client and provides strongly-typed methods for each operation.
  */
-import * as soap from "soap";
+import {${soapFactory.specifier}} from "soap";
+import type {${soapClient.specifier}, ${soapOptions.specifier}, ${soapSecurity.specifier}} from "soap";
 import type * as T from "./types${suffix}";
 import type {${clientName}DataTypes} from "./utils${suffix}";
 import {${clientConstant}_DATA_TYPES} from "./utils${suffix}";${anyStream ? `
@@ -195,11 +208,11 @@ export type ${clientName}Response<ResponseType, HeadersType = Record<string, unk
  */
 export class ${clientName} {
   protected source: string;
-  protected options?: soap.IOptions;
-  protected security?: soap.ISecurity;
+  protected options?: ${soapOptions.local};
+  protected security?: ${soapSecurity.local};
   protected attributesKeyIn: string;
   protected attributesKeyOut: string;
-  protected client?: soap.Client;
+  protected client?: ${soapClient.local};
   protected dataTypes: ${clientName}DataTypes = ${clientConstant}_DATA_TYPES;
 
   /**
@@ -214,8 +227,8 @@ export class ${clientName} {
    */
   constructor(options: {
     source: string,
-    options?: soap.IOptions,
-    security?: soap.ISecurity,
+    options?: ${soapOptions.local},
+    security?: ${soapSecurity.local},
     attributesKeyIn?: string,
     attributesKeyOut?: string
   }) {
@@ -237,7 +250,7 @@ export class ${clientName} {
    * @returns The initialized SOAP client instance.
    * @throws Error if the WSDL source is invalid or client creation fails.
    */
-  async soapClient(): Promise<soap.Client> {
+  async soapClient(): Promise<${soapClient.local}> {
     // If client is not initialized or has no WSDL source, create a new one
     if (!this.client || !this.client.wsdl) {
       // Note: source can be a URL or a local WSDL file path
@@ -246,7 +259,7 @@ export class ${clientName} {
       }
       try {
         // Create the SOAP client using the provided source and options
-        this.client = await soap.createClientAsync(this.source, this.options || {});
+        this.client = await ${soapFactory.local}(this.source, this.options || {});
         if (this.security) {
           this.client.setSecurity(this.security);
         }

package/docs/generated-code.md

@@ -106,6 +106,10 @@ See ESLint's [ignore documentation](https://eslint.org/docs/latest/use/configure
 
 ## Client Construction
 
+Generated clients import `createClientAsync` from `soap` at runtime and use type-only imports for `Client`,
+`IOptions`, and `ISecurity`. Imports are aliased when a generated client class uses the same name.
+Type-only imports are erased from JavaScript; install `soap` as a runtime dependency for the client factory.
+
 ```typescript
 import soap from "soap";
 import { Weather } from "./src/services/weather/client.js";

package/docs/releases/v1.1.4.md

@@ -0,0 +1,36 @@
+# TypeScript WSDL Client v1.1.4
+
+## Explicit SOAP imports in generated clients
+
+This patch replaces generated SOAP namespace imports with named runtime imports and explicit type-only imports. See the [project overview](../../README.md) for the generation pipeline.
+
+## What This Improves
+
+Generated clients compile with strict NodeNext and verbatim module syntax while importing only the SOAP runtime function they use. Custom client names that match SOAP exports receive local aliases, so client generation stays valid for names such as `Client`, `IOptions`, `ISecurity`, and `createClientAsync`.
+
+Buffered and streamed clients retain their existing behavior. Integration tests now have a dedicated typecheck, and both Node 24 and Node 26 CI exercise compiled generated clients.
+
+## Highlights
+
+- Generate a named `createClientAsync` import and type-only `Client`, `IOptions`, and `ISecurity` imports.
+- Alias SOAP imports when a custom generated client name would collide with an imported identifier.
+- Validate buffered and streamed clients against the actual SOAP declarations and Node runtime.
+- Typecheck integration tests and run compiled-client coverage in Node 26 CI.
+
+## Upgrade Notes
+
+Update the package and regenerate clients to receive the new imports. No generated API or configuration migration is required.
+
+Updates from v1.1.2 also include the dependency security maintenance prepared in v1.1.3. TypeScript remains on the maintained 6.x line, and Node 24 remains the minimum supported runtime.
+
+## Validation
+
+- Full CI passed with 662 unit, snapshot, integration, and conformance tests.
+- Buffered and streamed generated clients compile and execute under Node 24 and Node 26 checks.
+- Installed package checks validate 73 generated TypeScript artifacts and exercise local SOAP transport.
+- Release preflight validates package contents, dependency alignment, generated examples, and workflow gates.
+- The agent skill ZIP and checksum manifest are validated and packaged.
+
+## Notes
+
+Release tag: `v1.1.4`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Turn legacy WSDL/SOAP services into typed TypeScript clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways. Built for enterprise SOAP modernization.",
   "keywords": [
     "wsdl",
@@ -67,6 +67,7 @@
     "clean:tmp": "rimraf tmp",
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit",
+    "typecheck:integration": "tsc -p test/integration/tsconfig.json",
     "test": "vitest run",
     "test:unit": "vitest run test/unit",
     "test:snap": "vitest run test/snapshot",
@@ -99,9 +100,9 @@
     "package:smoke": "node scripts/smoke-npm-package.mjs",
     "release:preflight": "node scripts/release-preflight.mjs",
     "release:publish-check": "npm run clean && npm run build && npm run typecheck && npm run skill:validate && npm run package:validate",
-    "ci": "npm run clean && npm run build && npm run typecheck && npm run skill:validate && npm run package:validate && npm run docs:validate && vitest run && npm run smoke:pipeline && npm run package:smoke",
-    "ci:github": "npm run clean && npm run build && npm run typecheck && npm run skill:validate && npm run package:validate && npm run docs:validate && npm run test:github && npm run smoke:pipeline",
-    "ci:github:node26": "npm run clean && npm run build && npm run typecheck && npm run test:unit && npm run smoke:pipeline",
+    "ci": "npm run clean && npm run build && npm run typecheck && npm run typecheck:integration && npm run skill:validate && npm run package:validate && npm run docs:validate && vitest run && npm run smoke:pipeline && npm run package:smoke",
+    "ci:github": "npm run clean && npm run build && npm run typecheck && npm run typecheck:integration && npm run skill:validate && npm run package:validate && npm run docs:validate && npm run test:github && npm run smoke:pipeline",
+    "ci:github:node26": "npm run clean && npm run build && npm run typecheck && npm run typecheck:integration && npm run test:unit && vitest run test/integration/client-imports.test.ts && npm run smoke:pipeline",
     "examples:regenerate": "tsx src/cli.ts pipeline --wsdl-source examples/minimal/weather.wsdl --client-dir examples/generated-output/client --openapi-file examples/generated-output/openapi.json --gateway-dir examples/generated-output/gateway --gateway-service-name weather --gateway-version-prefix v1 --openapi-format json"
   },
   "devDependencies": {

package/src/runtime/clientStreamMethods.tpl.txt

@@ -60,7 +60,7 @@
    * SOAP address. Falls back to the \`source\` URL when the descriptor is
    * unavailable (e.g., \`source\` was given as a direct endpoint URL).
    */
-  protected resolveStreamEndpoint(client: soap.Client): string {
+  protected resolveStreamEndpoint(client: __SOAP_CLIENT_TYPE__): string {
     const services = (client as any)?.wsdl?.definitions?.services ?? {};
     for (const svc of Object.values(services)) {
       const ports = (svc as any)?.ports ?? {};