@techspokes/typescript-wsdl-client 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TechSpokes, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# TypeScript WSDL Client
+
+[![CI](https://github.com/techspokes/typescript-wsdl-client/actions/workflows/ci.yml/badge.svg)](https://github.com/techspokes/typescript-wsdl-client/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@techspokes/typescript-wsdl-client.svg)](https://www.npmjs.com/package/@techspokes/typescript-wsdl-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**TypeScript WSDL → SOAP client generator.**
+Reads WSDL/XSD (with imports) and emits a small, typed client you can compile into your app.
+
+* `xs:attribute` support (attributes become first-class fields, not bags)
+* `complexType` (`sequence` / `all` / `choice`)
+* `simpleContent` / `complexContent` (`extension` + `restriction`)
+* Inline **anonymous** types (auto-named, stable)
+* Global `element @ref` resolution
+* Duplicate/local-name **merge** across schemas/namespaces
+* Deterministic metadata (`ATTR_SPEC`, `PROP_META`) for clean JSON ⇄ SOAP mapping
+* ESM **and** CommonJS friendly output
+
+Vendor: **[TechSpokes](https://www.techspokes.com)** · Contact: **[contact@techspokes.com](mailto:contact@techspokes.com)**
+Maintainer: **Serge Liatko** ([@sergeliatko](https://github.com/sergeliatko)) · GitHub org: [@techspokes](https://github.com/techspokes)
+
+---
+
+## Quick start
+
+Install the generator (dev-time) in your project:
+
+```bash
+npm i -D typescript-wsdl-client
+# your app will use node-soap at runtime:
+npm i soap
+```
+
+Generate into your app (recommended under `src/generated/...`):
+
+```bash
+npx wsdl-tsc --wsdl ./spec/wsdl/MyService.wsdl --out ./src/generated/my --imports js --ops-ts
+```
+
+Use the generated client:
+
+```ts
+// ESM / NodeNext app
+import { createSoapClient } from "./generated/my/runtime.js";
+import { GeneratedSoapClient } from "./generated/my/client.js";
+
+const soap = await createSoapClient({ wsdlUrl: "https://example.com/MyService?wsdl" });
+const client = new GeneratedSoapClient(soap, "$attributes"); // attributes key optional
+
+const rs = await client.MyOperation({
+  MyOperationRQ: {
+    MyAttribute: "passed as attribute",
+    MyElement: "passed as child element",
+    // ...other fields
+    // attributes appear as top-level props; child elements as nested objects
+  }
+});
+
+console.log(rs);
+```
+
+> The generator always emits TypeScript sources (`*.ts`). You compile them with your app.
+
+---
+
+## CLI
+
+```
+wsdl-tsc --wsdl <path-or-url> --out <dir> [options]
+```
+
+**Required**
+
+* `--wsdl` — WSDL path or URL
+* `--out` — output directory (created if missing)
+
+**Useful options**
+
+* `--imports js|ts|bare` (default: `js`)
+  How intra-generated imports are written:
+
+    * `js` → `./file.js` (best for ESM/NodeNext apps)
+    * `ts` → `./file.ts` (use with `allowImportingTsExtensions`)
+    * `bare` → `./file` (nice for CommonJS builds)
+* `--ops-ts` (default: `true`)
+  Emit `operations.ts` instead of JSON.
+
+**Primitive mapping (safe defaults)**
+
+* `--int64-as string|number|bigint` (default `string`) — `xs:long`, `xs:unsignedLong`
+* `--bigint-as string|number` (default `string`) — `xs:integer` family
+* `--decimal-as string|number` (default `string`) — `xs:decimal` (money/precision)
+* `--date-as string|Date` (default `string`) — `xs:date`, `xs:dateTime`, `xs:time`, `g*`, durations
+
+**Other**
+
+* `--attributes-key <string>` (default: `$attributes`)
+  The key used by the runtime marshaller when serializing attributes.
+
+---
+
+## What gets generated
+
+```
+<out>/
+  types.ts       # interfaces + type aliases (with @xsd JSDoc: original XML type/occurs)
+  client.ts      # thin operation wrapper (calls into runtime)
+  runtime.ts     # small SOAP runtime: createSoapClient, toSoapArgs, fromSoapResult
+  meta.ts        # ATTR_SPEC, CHILD_TYPE, PROP_META for JSON ⇄ SOAP mapping
+  operations.ts  # compiled operation metadata (name, soapAction, etc.)
+```
+
+Example: if `User` has `@Id` and `@CreatedAt`, you’ll see:
+
+```ts
+interface User {
+  Id?: string;
+  CreatedAt?: string; // or Date if you chose --date-as Date
+}
+```
+
+---
+
+## Using in different app module systems
+
+### ESM / NodeNext (recommended)
+
+Service `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+Generate with `--imports js` and import `./client.js`, `./runtime.js`.
+
+### CommonJS
+
+Keep your app `module: "CommonJS"` and generate with `--imports bare` (imports like `./runtime`).
+TypeScript will compile to `require("./runtime")` cleanly.
+
+---
+
+## Recommended workflow
+
+* **Vendor** your WSDL(s) in `spec/wsdl/` for reproducible builds.
+* Generate into `src/generated/<service>/` and **commit the generated files** (deterministic CI/Docker).
+* Build your app (the generated code compiles with it).
+
+**Example scripts (app `package.json`):**
+
+```json
+{
+  "scripts": {
+    "codegen:my": "wsdl-tsc --wsdl ./spec/wsdl/MyService.wsdl --out ./src/generated/my --imports js --ops-ts",
+    "prebuild": "npm run codegen:my",
+    "build": "tsc -p tsconfig.json"
+  }
+}
+```
+
+---
+
+## Programmatic API (optional)
+
+```ts
+import { compileCatalog, xsdToTsPrimitive, type CompilerOptions } from "typescript-wsdl-client";
+import { loadWsdlCatalog } from "typescript-wsdl-client/internal-or-your-loader"; // if you expose it
+
+const catalog = await loadWsdlCatalog("./spec/wsdl/MyService.wsdl");
+const compiled = compileCatalog(catalog, {
+  primitive: { decimalAs: "string", dateAs: "string" }
+});
+// …write your own emitters or use the built-ins in the CLI.
+```
+
+---
+
+## Primitive mapping rationale
+
+Defaults are **string-first** to avoid precision & timezone surprises:
+
+* `xs:decimal` → `string` (money/precision safe)
+* 64-bit integers → `string` (you can opt into `bigint` or `number`)
+* dates/times → `string` (transport-friendly, no implicit tz conversion)
+
+Change per your needs with the CLI flags above.
+
+---
+
+## Minimal test you can run
+
+```bash
+# generate from a local WSDL
+npx wsdl-tsc --wsdl ./spec/wsdl/MyService.wsdl --out ./tmp --imports js --ops-ts
+
+# quick typecheck of generated output (NodeNext)
+npx tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 ./tmp/*.ts
+```
+
+---
+
+## Troubleshooting
+
+* **“I don’t see `runtime.ts`”** — You should. Ensure you’re on a recent version and check that the output directory is writable.
+* **“Cannot find './runtime.js'”** — Your app must be `module: "NodeNext"` when using `--imports js`.
+  Use `--imports bare` for CommonJS apps.
+* **“node-soap not found”** — Install it in your **app**: `npm i soap`.
+
+---
+
+## Contributing
+
+Issues and PRs welcome. Please include a **minimal WSDL/XSD** fixture that reproduces the case.
+Node 20+ supported.
+
+- See CONTRIBUTING.md for setup and workflow.
+- See CODE_OF_CONDUCT.md for community expectations.
+- Security reports: see SECURITY.md.
+
+---
+
+## Community
+
+- Contributing guide: CONTRIBUTING.md
+- Code of Conduct: CODE_OF_CONDUCT.md
+- Security policy: SECURITY.md
+- Support: SUPPORT.md
+- Roadmap: ROADMAP.md
+- Changelog: CHANGELOG.md
+
+---
+
+## License
+
+MIT © TechSpokes.
+*The tool is MIT-licensed. Generated artifacts are owned by you; the tool imposes no license on generated files.*

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import yargs from "yargs/yargs";
+import { hideBin } from "yargs/helpers";
+import fs from "node:fs";
+import path from "node:path";
+import { loadWsdl } from "./loader/wsdlLoader.js";
+import { compileCatalog } from "./compiler/schemaCompiler.js";
+import { emitRuntime } from "./emit/runtimeEmitter.js";
+import { emitTypes } from "./emit/typesEmitter.js";
+import { emitMeta } from "./emit/metaEmitter.js";
+import { emitOps } from "./emit/opsEmitter.js";
+import { emitClient } from "./emit/clientEmitter.js";
+const argv = await yargs(hideBin(process.argv))
+    .scriptName("wsdl-tsc")
+    .option("wsdl", {
+    type: "string",
+    demandOption: true,
+    desc: "Path or URL to the WSDL"
+})
+    .option("out", {
+    type: "string",
+    demandOption: true,
+    desc: "Output directory for generated files"
+})
+    .option("imports", {
+    type: "string",
+    choices: ["js", "ts", "bare"],
+    default: "js",
+    desc: "Intra-generated import specifiers: '.js', '.ts', or bare (no extension)",
+})
+    .option("ops-ts", {
+    type: "boolean",
+    default: true,
+    desc: "Emit operations.ts instead of JSON",
+})
+    .option("attributes-key", {
+    type: "string",
+    default: "$attributes",
+    desc: "Key used by runtime marshaller for XML attributes",
+})
+    // Primitive mapping knobs (safe defaults)
+    .option("int64-as", {
+    type: "string",
+    choices: ["string", "number", "bigint"],
+    default: "string",
+    desc: "How to map xs:long/xs:unsignedLong",
+})
+    .option("bigint-as", {
+    type: "string",
+    choices: ["string", "number"],
+    default: "string",
+    desc: "How to map xs:integer family (positive/nonNegative/etc.)",
+})
+    .option("decimal-as", {
+    type: "string",
+    choices: ["string", "number"],
+    default: "string",
+    desc: "How to map xs:decimal (money/precision)",
+})
+    .option("date-as", {
+    type: "string",
+    choices: ["string", "Date"],
+    default: "string",
+    desc: "How to map date/time/duration types",
+})
+    .strict()
+    .help()
+    .parse();
+const outDir = path.resolve(String(argv.out));
+fs.mkdirSync(outDir, { recursive: true });
+// Load & compile
+const catalog = await loadWsdl(String(argv.wsdl));
+const compiled = compileCatalog(catalog, {
+    primitive: {
+        int64As: argv["int64-as"],
+        bigIntegerAs: argv["bigint-as"],
+        decimalAs: argv["decimal-as"],
+        dateAs: argv["date-as"],
+    },
+});
+// Emit files
+const importExt = argv.imports === "js" ? ".js" : argv.imports === "ts" ? ".ts" : "";
+emitTypes(path.join(outDir, "types.ts"), compiled);
+emitMeta(path.join(outDir, "meta.ts"), compiled);
+emitOps(path.join(outDir, argv["ops-ts"] ? "operations.ts" : "operations.json"), compiled);
+emitRuntime(path.join(outDir, "runtime.ts"));
+emitClient(path.join(outDir, "client.ts"), compiled, {
+    // These fields are consumed by our client emitter options shape
+    // to keep CLI flexible without exposing full CompilerOptions here.
+    // @ts-ignore runtime-only options for emitter
+    importExt,
+    attributesKey: String(argv["attributes-key"]),
+});
+console.log(`✅ Generated TypeScript client in ${outDir}`);

package/dist/compiler/schemaCompiler.d.ts

@@ -0,0 +1,50 @@
+import type { CompilerOptions } from "../config.js";
+import type { WsdlCatalog } from "../loader/wsdlLoader.js";
+export type QName = {
+    ns: string;
+    local: string;
+};
+export type CompiledType = {
+    name: string;
+    ns: string;
+    attrs: Array<{
+        name: string;
+        tsType: string;
+        use?: "required" | "optional";
+        declaredType: string;
+    }>;
+    elems: Array<{
+        name: string;
+        tsType: string;
+        min: number;
+        max: number | "unbounded";
+        nillable?: boolean;
+        declaredType: string;
+    }>;
+    jsdoc?: string;
+};
+export type CompiledAlias = {
+    name: string;
+    ns: string;
+    tsType: string;
+    declared: string;
+    jsdoc?: string;
+};
+export type CompiledCatalog = {
+    types: CompiledType[];
+    aliases: CompiledAlias[];
+    meta: {
+        attrSpec: Record<string, string[]>;
+        childType: Record<string, Record<string, string>>;
+        propMeta: Record<string, Record<string, any>>;
+    };
+    operations: Array<{
+        name: string;
+        soapAction: string;
+        inputElement?: QName;
+        outputElement?: QName;
+    }>;
+    wsdlTargetNS: string;
+};
+export declare function compileCatalog(cat: WsdlCatalog, _opts: CompilerOptions): CompiledCatalog;
+//# sourceMappingURL=schemaCompiler.d.ts.map

package/dist/compiler/schemaCompiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaCompiler.d.ts","sourceRoot":"","sources":["../../src/compiler/schemaCompiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAU3D,MAAM,MAAM,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;QAC9B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC;QAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAClD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;KAC/C,CAAC;IACF,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,KAAK,CAAC;QACrB,aAAa,CAAC,EAAE,KAAK,CAAC;KACvB,CAAC,CAAC;IACH,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAoBF,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,GAAG,eAAe,CA+XxF"}