@gusnips/sdkgen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Salomé
+
+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,127 @@
+# @gusnips/sdkgen
+
+The parts of a script that writes a TypeScript SDK for your API. You keep the script, because the
+methods it writes are yours. This package holds the parts that are easy to get wrong.
+
+```bash
+bun add -d @gusnips/sdkgen prettier
+```
+
+```ts
+import { typeOf } from "@gusnips/sdkgen";
+
+typeOf({ type: ["string", "null"] });
+// → "string | null"
+```
+
+`typeOf` turns a JSON Schema into the TypeScript type it describes. A zod schema works too, through
+`inputJsonSchema`, and each field keeps its description as a doc comment:
+
+```ts
+import { z } from "zod";
+import { fieldsOf, inputJsonSchema } from "@gusnips/sdkgen";
+
+fieldsOf(inputJsonSchema(z.object({ to: z.string().describe("Who gets it.") })));
+// → "    /** Who gets it. */\n    to: string;\n"
+```
+
+## What is in it
+
+| Function                  | What it does                                                                       |
+| ------------------------- | ---------------------------------------------------------------------------------- |
+| `liftContract`            | Copies the types your API answers with into one file, comments included.           |
+| `typeOf`                  | Writes a JSON Schema as a TypeScript type.                                         |
+| `fieldsOf`                | Writes an object schema's fields, one per line, each description as a doc comment. |
+| `paramsInterface`         | Writes `export interface SendParams { … }`, and says if every field is optional.   |
+| `docComment`              | Writes `/** … */`, wrapped at 96 columns.                                          |
+| `wrapLines`               | Breaks prose into lines for a comment you lay out yourself.                        |
+| `typeNames`               | Lists the type names in an expression: `Page<Job>[]` gives `Page` and `Job`.       |
+| `camelCase`, `pascalCase` | `send_message` gives `sendMessage` and `SendMessage`.                              |
+| `inputJsonSchema`         | Turns a zod schema into JSON Schema. JSON Schema passes through as it is.          |
+| `writeGenerated`          | Formats and writes the files, or lists the ones that are out of date.              |
+
+## Copy your API's types
+
+An SDK is published on its own, so it cannot import your API's code. The types it returns have to
+be copied into it.
+
+```ts
+import { liftContract } from "@gusnips/sdkgen";
+
+const contract = liftContract({
+  root: repoRoot,
+  sources: ["packages/shared/src/http.ts", "packages/shared/src/dto.ts"],
+  roots: ["ApiError", "MessageDto"],
+});
+```
+
+That returns one file's text. It has each name in `roots` with its doc comment, then every type
+those mention, in the order they appear in `sources`. If a name is declared nowhere, it stops and
+lists the files it searched.
+
+Two options change what comes out:
+
+- `inlineTuples: true` writes `(typeof STATUSES)[number]` as `"queued" | "sent" | "failed"` and
+  leaves the array out. Use it when the SDK has no use for the array. It is off by default, because
+  an SDK that re-exports its contract publishes that array, and each member's doc comment goes with
+  it.
+- `exportOnlyRoots: true` keeps `export` on the names in `roots` only. The types they mention are
+  still written, so the file compiles, but they are not part of the SDK's public names.
+
+It reads your files as text, not with the TypeScript compiler, because the compiler's `.d.ts`
+output drops the comments. It finds `export interface`, `export type`, `export const` and
+`export function` at the start of a line. Two limits:
+
+- A name of one or two letters, like `T` or `K`, is taken to be a type parameter and not followed.
+  If a real type has a name that short, the SDK will not compile, so you find out.
+- A quote inside a regex literal, like `/"/`, is read as the start of a string.
+
+## Keep the SDK current
+
+```ts
+import { writeGenerated } from "@gusnips/sdkgen";
+
+const files = { "packages/sdk/src/generated/contract.ts": contract };
+const { stale } = await writeGenerated(files, {
+  root: repoRoot,
+  check: process.argv.includes("--check"),
+});
+if (stale.length > 0) {
+  console.error(`Out of date:\n  ${stale.join("\n  ")}\nRun \`bun run sdk:gen\` and commit.`);
+  process.exitCode = 1;
+}
+```
+
+`files` maps each path to its text. A relative path starts from `root`, and `stale` and `written`
+list paths the way `files` spells them. Each file is formatted with the prettier config for its
+path before it is compared or written, so `prettier --check` and `--check` always agree. With
+`check`, nothing is written. A file it cannot read, for a reason other than not existing, is an
+error and not "out of date".
+
+## Rules
+
+- **It never guesses a type.** A schema it does not understand, such as `allOf` or a `$ref`, throws
+  with the schema in the message. A wrong `unknown` in a published SDK hides the mistake from
+  everyone who installs it. It writes `unknown` only where the schema itself allows any value,
+  as `{}` does.
+- **A field name that is not an identifier is quoted:** `"content-type"?: string`.
+- **A `*/` in a description is broken up**, so it cannot end the doc comment early.
+- **A zod schema needs zod 4.4 or later.** Older versions cannot describe themselves as JSON
+  Schema, and the error says so.
+
+## Why it exists
+
+Five APIs each wrote their own SDK generator, about 2,500 lines in all. They were not copies. Each
+had fixed something the others had not, and every one still had these bugs:
+
+- A backslash at the end of a `//` comment hid the next line, so the declaration under it was never
+  found.
+- A string with a backslash before its line break moved every later line by one, so the generator
+  copied the wrong text for every declaration after it in the file.
+- `export interface Empty {}` on one line swallowed the declaration after it.
+- A comment written `/*/` ended on the character that opened it.
+
+This package is the merge, with each fix pinned by a test. Two of those generators were rewritten
+on it and wrote every file byte for byte as before, 268 and 281 lines shorter.
+
+MIT

package/dist/contract.d.ts

@@ -0,0 +1,40 @@
+export interface LiftOptions {
+    /** The directory `sources` are relative to, usually the repo root. */
+    root: string;
+    /** The files a public type may come from. They are written out in this order. */
+    sources: readonly string[];
+    /** The names the SDK needs. Everything they mention comes along. */
+    roots: readonly string[];
+    /**
+     * Write `(typeof X)[number]` as its literal union, and leave the array out. Off by default: an SDK
+     * that re-exports its contract publishes that array, so dropping it is a breaking change, and
+     * each member's doc comment goes with it.
+     */
+    inlineTuples?: boolean;
+    /**
+     * Keep `export` on the roots only. What they mention is still written, without it, so the SDK's
+     * public names are exactly the ones listed. Off by default: everything written is exported.
+     */
+    exportOnlyRoots?: boolean;
+}
+/**
+ * The source with every comment and string body blanked, one character for one character and a
+ * newline for a newline, so structure can be read off it while the ORIGINAL lines are what gets
+ * copied. Without it a `;` inside a sentence ends a declaration early, and every capitalized word
+ * in the prose looks like a type. `keepStrings` blanks the comments only, for reading the strings
+ * themselves: an apostrophe in a comment is not a quote.
+ *
+ * ponytail: a regex literal is read as code, so a quote inside one (`/"/`) opens a string that
+ * runs to the next quote. Contract files are declarations, where that does not come up; one that
+ * needs it would need a real tokenizer here.
+ */
+export declare function blankCommentsAndStrings(source: string, { keepStrings }?: {
+    keepStrings?: boolean | undefined;
+}): string;
+/**
+ * Every declaration the roots need, in source order, as one file's text. A name nobody declares
+ * throws with the list of files searched: a contract with a dangling reference does not compile,
+ * and finding out here beats finding out at publish.
+ */
+export declare function liftContract({ root, sources, roots, inlineTuples, exportOnlyRoots, }: LiftOptions): string;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,oEAAoE;IACpE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,WAAmB,EAAE;;CAAK,GAAG,MAAM,CAyC5F;AAmGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,OAAO,EACP,KAAK,EACL,YAAoB,EACpB,eAAuB,GACxB,EAAE,WAAW,GAAG,MAAM,CAsCtB"}

package/dist/contract.js

@@ -0,0 +1,213 @@
+/**
+ * Copying the API's own type declarations into its SDK, with their comments.
+ *
+ * A published SDK cannot depend on the API's workspace, so the types it answers with have to
+ * travel inside it. A `.d.ts` emit would carry the types and drop the prose, and the prose is most
+ * of what makes an SDK pleasant to hold, so this reads each declaration as it is written at home
+ * and copies it whole. Five generators did this with one hand-written reader, and each copy had
+ * fixed something the others had not:
+ * - a property KEY is not a reference (`VALIDATION_ERROR: 400` names no type);
+ * - an `export function` is a braced block, like an interface;
+ * - `(typeof X)[number]` can be written as its literal union, where the array would be dead.
+ * And all five broke what the reader rests on, that the blanked text matches the original line for
+ * line: an escaped newline in a string moved every later line, a backslash at the end of a `//`
+ * comment blanked the next line, a `/*` followed by `/` closed on its own star, and a one-line
+ * `{}` block ran on into the next declaration.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { BUILTIN } from "./types.js";
+/**
+ * The source with every comment and string body blanked, one character for one character and a
+ * newline for a newline, so structure can be read off it while the ORIGINAL lines are what gets
+ * copied. Without it a `;` inside a sentence ends a declaration early, and every capitalized word
+ * in the prose looks like a type. `keepStrings` blanks the comments only, for reading the strings
+ * themselves: an apostrophe in a comment is not a quote.
+ *
+ * ponytail: a regex literal is read as code, so a quote inside one (`/"/`) opens a string that
+ * runs to the next quote. Contract files are declarations, where that does not come up; one that
+ * needs it would need a real tokenizer here.
+ */
+export function blankCommentsAndStrings(source, { keepStrings = false } = {}) {
+    let out = "";
+    let state = "code";
+    const blank = (c) => (c === "\n" ? "\n" : c === undefined ? "" : " ");
+    const inString = (c) => (keepStrings ? (c ?? "") : blank(c));
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i] ?? "";
+        const next = source[i + 1];
+        if (state === "code") {
+            if (c === "/" && (next === "/" || next === "*")) {
+                // Both characters of the opener, so the `*` of `/*/` cannot also close it.
+                state = next === "/" ? "line" : "block";
+                out += "  ";
+                i++;
+            }
+            else if (c === '"' || c === "'" || c === "`") {
+                state = c;
+                out += inString(c);
+            }
+            else
+                out += c;
+            continue;
+        }
+        if (state === "line" || state === "block") {
+            if (state === "block" && c === "*" && next === "/") {
+                state = "code";
+                out += "  ";
+                i++;
+                continue;
+            }
+            if (c === "\n" && state === "line")
+                state = "code";
+            out += blank(c);
+            continue;
+        }
+        if (c === "\\") {
+            // An escape never closes a string, and the character it escapes may be a newline.
+            out += inString(c) + inString(next);
+            i++;
+            continue;
+        }
+        if (c === state)
+            state = "code";
+        out += inString(c);
+    }
+    return out;
+}
+/** Split one file into its exported top-level declarations. */
+function readBlocks(text) {
+    const lines = text.split("\n");
+    const clean = blankCommentsAndStrings(text).split("\n");
+    const blocks = [];
+    for (let i = 0; i < lines.length; i++) {
+        const match = /^export (interface|type|const|function) (\w+)/.exec(clean[i] ?? "");
+        if (!match?.[2])
+            continue;
+        const name = match[2];
+        // Back over the doc comment sitting on top of the declaration.
+        let start = i;
+        while (start > 0) {
+            const above = (lines[start - 1] ?? "").trim();
+            if (!above || (!above.startsWith("*") && !above.startsWith("/*")))
+                break;
+            start--;
+        }
+        // Forward to its end: the first `;` outside every bracket, since a mapped type carries one on
+        // an inner line, or for an interface or a function, the line that closes its brackets. That
+        // can be its first (`export interface Empty {}`); waiting for a lone `}`, as every copy did,
+        // swallowed the declaration after it.
+        const braced = match[1] === "interface" || match[1] === "function";
+        let end = i;
+        let depth = 0;
+        outer: for (; end < lines.length; end++) {
+            for (const char of clean[end] ?? "") {
+                if ("{[(".includes(char))
+                    depth++;
+                else if ("}])".includes(char))
+                    depth--;
+                else if (char === ";" && depth === 0)
+                    break outer;
+            }
+            if (braced && depth === 0)
+                break;
+        }
+        const body = clean
+            .slice(i, end + 1)
+            .join("\n")
+            // A property KEY is not a reference: `VALIDATION_ERROR: 400` names a member, not a type.
+            .replace(/\b[A-Z][A-Za-z0-9_]*(?=\s*\??:)/g, " ");
+        const refs = [...new Set(body.match(/\b[A-Z][A-Za-z0-9_]*\b/g) ?? [])].filter(
+        // ponytail: a short name is taken for a type parameter (`T`, `K`). A wrong guess is loud,
+        // not silent: a skipped name that WAS needed leaves the SDK missing a type, and it stops
+        // compiling.
+        (ref) => ref !== name && ref.length > 2 && !BUILTIN.has(ref));
+        blocks.push({ name, source: lines.slice(start, end + 1).join("\n"), refs });
+        i = end;
+    }
+    return blocks;
+}
+/**
+ * With `inlineTuples`, `export type Plan = (typeof PLANS)[number];` becomes
+ * `export type Plan = "free" | "pro";`, and the array is left out. Only a tuple of plain string
+ * literals qualifies; anything else throws, because guessing a union into a published type is
+ * worse than stopping.
+ */
+function inlineTupleUnions(index) {
+    for (const block of index.values()) {
+        const alias = /export type (\w+) = \(?typeof (\w+)\)?\[number\];/.exec(block.source);
+        if (!alias?.[2])
+            continue;
+        const tuple = index.get(alias[2]);
+        if (tuple === undefined)
+            continue; // reported as missing below
+        // Comments out first, strings kept: a member's doc comment can hold an apostrophe.
+        const code = blankCommentsAndStrings(tuple.source, { keepStrings: true });
+        const literal = /=\s*\[([\s\S]*?)\]\s*as const\s*;/.exec(code);
+        const members = literal?.[1]?.match(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g) ?? [];
+        const rest = literal?.[1]?.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, "");
+        if (literal === null || rest === undefined || /[^\s,]/.test(rest)) {
+            throw new Error(`${alias[2]} must be a tuple of string literals \`as const\` for ${block.name} to be written as a union.`);
+        }
+        const union = members.map((member) => {
+            let unreadable = false;
+            const text = member.slice(1, -1).replace(/\\([\s\S])/g, (_escape, char) => {
+                unreadable ||= !`"'\\`.includes(char);
+                return char;
+            });
+            // ponytail: only a quote or a backslash is unescaped. Any other escape (`\n`, `\u00e9`)
+            // needs the language's whole table, so it stops rather than write a wrong member.
+            if (unreadable) {
+                throw new Error(`${alias[2]} has a member with an escape this cannot read: ${member}. Write it without one, or leave inlineTuples off.`);
+            }
+            return JSON.stringify(text);
+        });
+        block.source = block.source.replace(alias[0], `export type ${block.name} = ${union.join(" | ") || "never"};`);
+        block.refs = [];
+    }
+}
+/**
+ * Every declaration the roots need, in source order, as one file's text. A name nobody declares
+ * throws with the list of files searched: a contract with a dangling reference does not compile,
+ * and finding out here beats finding out at publish.
+ */
+export function liftContract({ root, sources, roots, inlineTuples = false, exportOnlyRoots = false, }) {
+    const files = sources.map((file) => ({
+        file,
+        blocks: readBlocks(readFileSync(join(root, file), "utf8")),
+    }));
+    const index = new Map();
+    for (const { blocks } of files)
+        for (const block of blocks)
+            index.set(block.name, block);
+    if (inlineTuples)
+        inlineTupleUnions(index);
+    const needed = new Set();
+    const missing = new Set();
+    const visit = (name) => {
+        if (needed.has(name))
+            return;
+        const block = index.get(name);
+        if (block === undefined) {
+            missing.add(name);
+            return;
+        }
+        needed.add(name);
+        block.refs.forEach(visit);
+    };
+    roots.forEach(visit);
+    if (missing.size > 0) {
+        throw new Error(`No declaration found for ${[...missing].join(", ")}. Export it from one of:\n  ${sources.join("\n  ")}`);
+    }
+    const chunks = [];
+    for (const { file, blocks } of files) {
+        const wanted = blocks.filter((b) => needed.has(b.name));
+        if (wanted.length === 0)
+            continue;
+        chunks.push(`// ── from ${file} ${"─".repeat(Math.max(0, 60 - file.length))}\n`);
+        const text = (b) => exportOnlyRoots && !roots.includes(b.name) ? b.source.replace(/^export /m, "") : b.source;
+        chunks.push(wanted.map(text).join("\n\n"));
+    }
+    return chunks.join("\n");
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { liftContract, type LiftOptions } from "./contract.ts";
+export { camelCase, docComment, fieldsOf, inputJsonSchema, paramsInterface, pascalCase, typeNames, typeOf, wrapLines, type JsonObject, type SchemaSource, type StandardJsonSchema, } from "./types.ts";
+export { writeGenerated, type GeneratedFiles, type WriteOptions, type WriteResult, } from "./write.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,MAAM,EACN,SAAS,EACT,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { liftContract } from "./contract.js";
+export { camelCase, docComment, fieldsOf, inputJsonSchema, paramsInterface, pascalCase, typeNames, typeOf, wrapLines, } from "./types.js";
+export { writeGenerated, } from "./write.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAoB,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,MAAM,EACN,SAAS,GAIV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,GAIf,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Writing a JSON Schema as a TypeScript type, with each field's description kept as its doc
+ * comment.
+ *
+ * Five generators each wrote this, and the fixes were spread across them: `type: [..., "null"]`
+ * in three, `{}` as `unknown` and a record as `Record<string, T>` in two, a boolean schema and a
+ * tuple in one. The rule all five kept is the one that matters most: **never guess a type into a
+ * published SDK.** A schema node this does not understand throws; it never becomes `unknown`.
+ */
+export type JsonObject = Record<string, unknown>;
+/** The part of the Standard JSON Schema interface this module calls: zod 4.4 and later. */
+export interface StandardJsonSchema {
+    "~standard": {
+        vendor: string;
+        jsonSchema?: {
+            input(options: {
+                target: "draft-2020-12";
+                libraryOptions?: JsonObject;
+            }): JsonObject;
+            output(options: {
+                target: "draft-2020-12";
+                libraryOptions?: JsonObject;
+            }): JsonObject;
+        };
+    };
+}
+/** A schema: a Standard JSON Schema such as a zod object, or JSON Schema itself. */
+export type SchemaSource = StandardJsonSchema | JsonObject;
+/** The schema as JSON Schema, describing what a caller SENDS. */
+export declare function inputJsonSchema(source: SchemaSource): JsonObject;
+/** Names TypeScript itself provides, so a mention of one is not a declaration to find. */
+export declare const BUILTIN: Set<string>;
+/**
+ * The TypeScript type for one schema. `indent` is where the enclosing line starts, so an inline
+ * object's fields land one level in.
+ */
+export declare function typeOf(schema: JsonObject | boolean, indent?: string): string;
+/**
+ * An object schema's fields, one per line, each description kept as a doc comment. `skip` leaves
+ * fields out, such as the ones a route fills in itself.
+ */
+export declare function fieldsOf(schema: JsonObject, indent?: string, skip?: readonly string[]): string;
+/**
+ * `export interface SendMessageParams { … }`, or `null` when the schema has no fields left. The
+ * interface is `optional` when no remaining field is required, so the method's argument can be.
+ */
+export declare function paramsInterface(name: string, schema: JsonObject, skip?: readonly string[]): {
+    source: string;
+    optional: boolean;
+} | null;
+/**
+ * Prose broken into lines of at most `96 - indent.length` characters, to sit inside a comment at
+ * that indent. Every caller puts them in one, so a star-slash is broken up here: it would end the
+ * comment early and turn the rest of the sentence into code.
+ *
+ * ```ts
+ * wrapLines(op.description, "    ").join("\n     * ");
+ * ```
+ */
+export declare function wrapLines(text: string, indent?: string): string[];
+/**
+ * `/** text *\/`, with continuation lines under the opener: the format all five generators wrote
+ * for a field, byte for byte.
+ */
+export declare function docComment(text: string, indent?: string): string;
+/**
+ * The declared names a type expression mentions: `"V1ListPage<JobDto>[] | null"` needs
+ * `V1ListPage` and `JobDto`. Splitting on `|` alone, as one generator did, misses what sits
+ * inside the generic.
+ */
+export declare function typeNames(expression: string): string[];
+/** `send_message` → `sendMessage`. */
+export declare const camelCase: (name: string) => string;
+/** `send_message` → `SendMessage`. */
+export declare const pascalCase: (name: string) => string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE;YACX,KAAK,CAAC,OAAO,EAAE;gBAAE,MAAM,EAAE,eAAe,CAAC;gBAAC,cAAc,CAAC,EAAE,UAAU,CAAA;aAAE,GAAG,UAAU,CAAC;YACrF,MAAM,CAAC,OAAO,EAAE;gBAAE,MAAM,EAAE,eAAe,CAAC;gBAAC,cAAc,CAAC,EAAE,UAAU,CAAA;aAAE,GAAG,UAAU,CAAC;SACvF,CAAC;KACH,CAAC;CACH;AAED,oFAAoF;AACpF,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,UAAU,CAAC;AAE3D,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAShE;AAmBD,0FAA0F;AAC1F,eAAO,MAAM,OAAO,aA+BlB,CAAC;AAYH;;;GAGG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,EAAE,MAAM,SAAK,GAAG,MAAM,CAqDxE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,UAAU,EAClB,MAAM,SAAS,EACf,IAAI,GAAE,SAAS,MAAM,EAAO,GAC3B,MAAM,CAcR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,SAAS,MAAM,EAAO,GAC3B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAQ9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAS,GAAG,MAAM,EAAE,CAYjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAS,GAAG,MAAM,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAGtD;AAED,sCAAsC;AACtC,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,MACsB,CAAC;AAEhE,sCAAsC;AACtC,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,MAGzC,CAAC"}