@gusnips/sdkgen 0.1.0

package/dist/types.js

@@ -0,0 +1,222 @@
+/**
+ * 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`.
+ */
+/** The schema as JSON Schema, describing what a caller SENDS. */
+export function inputJsonSchema(source) {
+    if (!isStandard(source))
+        return source;
+    const standard = source["~standard"];
+    if (standard.jsonSchema === undefined) {
+        throw new Error(`This ${standard.vendor} schema cannot describe itself as JSON Schema. zod does from 4.4.`);
+    }
+    return standard.jsonSchema.input({ target: "draft-2020-12" });
+}
+function isStandard(source) {
+    return "~standard" in source;
+}
+/** Keywords that describe a value without constraining it, so `{ description }` is still `{}`. */
+const ANNOTATIONS = new Set([
+    "$schema",
+    "$comment",
+    "title",
+    "description",
+    "default",
+    "examples",
+    "deprecated",
+    "readOnly",
+    "writeOnly",
+]);
+/** Names TypeScript itself provides, so a mention of one is not a declaration to find. */
+export const BUILTIN = new Set([
+    "Array",
+    "ArrayBuffer",
+    "Awaited",
+    "Blob",
+    "Capitalize",
+    "Date",
+    "Error",
+    "Exclude",
+    "Extract",
+    "Lowercase",
+    "Map",
+    "NonNullable",
+    "Omit",
+    "Parameters",
+    "Partial",
+    "Pick",
+    "Promise",
+    "Readonly",
+    "ReadonlyArray",
+    "ReadonlyMap",
+    "ReadonlySet",
+    "Record",
+    "RegExp",
+    "Required",
+    "ReturnType",
+    "Set",
+    "URL",
+    "Uint8Array",
+    "Uncapitalize",
+    "Uppercase",
+]);
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A schema that is `true`, `false` or an object; anything else is not a schema. */
+function asSchema(value) {
+    if (typeof value === "boolean" || isObject(value))
+        return value;
+    throw new Error(`Not a JSON Schema: ${JSON.stringify(value)}`);
+}
+/**
+ * The TypeScript type for one schema. `indent` is where the enclosing line starts, so an inline
+ * object's fields land one level in.
+ */
+export function typeOf(schema, indent = "") {
+    if (typeof schema === "boolean")
+        return schema ? "unknown" : "never";
+    const { enum: members, const: constant, type } = schema;
+    if (Array.isArray(members))
+        return members.map((v) => JSON.stringify(v)).join(" | ");
+    if (constant !== undefined)
+        return JSON.stringify(constant);
+    const union = schema["anyOf"] ?? schema["oneOf"];
+    if (Array.isArray(union))
+        return union.map((s) => typeOf(asSchema(s), indent)).join(" | ");
+    // `type: ["number", "null"]`: each member carries the rest of the node, such as its items.
+    if (Array.isArray(type))
+        return type.map((t) => typeOf({ ...schema, type: t }, indent)).join(" | ");
+    // The EMPTY schema, `{}`, is "any value": what zod writes for `z.unknown()`. There is no
+    // narrower type to give it, so this is a shape understood, not a guess.
+    if (Object.keys(schema).every((key) => ANNOTATIONS.has(key)))
+        return "unknown";
+    switch (type) {
+        case "string":
+            return "string";
+        case "number":
+        case "integer":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "array": {
+            const items = schema["items"];
+            // Fixed positions, each with its own type: `[number, number]`, never `number[]`, which
+            // would accept one.
+            const fixed = schema["prefixItems"] ?? (Array.isArray(items) ? items : undefined);
+            if (Array.isArray(fixed)) {
+                const rest = Array.isArray(items) || items === undefined || items === false
+                    ? ""
+                    : `, ...${typeOf(asSchema(items), indent)}[]`;
+                return `[${fixed.map((m) => typeOf(asSchema(m), indent)).join(", ")}${rest}]`;
+            }
+            const item = items === undefined ? "unknown" : typeOf(asSchema(items), indent);
+            // `("a" | "b")[]`: without the parens the union swallows the array, and only the last
+            // member becomes one.
+            return item.includes(" | ") ? `(${item})[]` : `${item}[]`;
+        }
+        case "object": {
+            const fields = fieldsOf(schema, `${indent}    `);
+            if (fields)
+                return `{\n${fields}${indent}}`;
+            const values = schema["additionalProperties"];
+            // A record, such as headers: no named fields, one type for every value.
+            return isObject(values)
+                ? `Record<string, ${typeOf(values, indent)}>`
+                : "Record<string, unknown>";
+        }
+        default:
+            throw new Error(`Cannot write this JSON Schema as a type: ${JSON.stringify(schema)}`);
+    }
+}
+/**
+ * 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 function fieldsOf(schema, indent = "    ", skip = []) {
+    const properties = isObject(schema["properties"]) ? schema["properties"] : {};
+    const required = new Set(Array.isArray(schema["required"]) ? schema["required"] : []);
+    let out = "";
+    for (const [name, raw] of Object.entries(properties)) {
+        if (skip.includes(name))
+            continue;
+        const field = asSchema(raw);
+        const description = typeof field === "object" ? field["description"] : undefined;
+        if (typeof description === "string")
+            out += docComment(description, indent);
+        // A name that is not an identifier, such as `content-type`, has to be quoted.
+        const key = /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+        out += `${indent}${key}${required.has(name) ? "" : "?"}: ${typeOf(field, indent)};\n`;
+    }
+    return out;
+}
+/**
+ * `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 function paramsInterface(name, schema, skip = []) {
+    const fields = fieldsOf(schema, "    ", skip);
+    if (!fields)
+        return null;
+    const required = Array.isArray(schema["required"]) ? schema["required"] : [];
+    return {
+        source: `export interface ${name} {\n${fields}}\n`,
+        optional: !required.some((field) => typeof field === "string" && !skip.includes(field)),
+    };
+}
+/**
+ * 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 function wrapLines(text, indent = "    ") {
+    const width = 96 - indent.length;
+    const lines = [];
+    let line = "";
+    for (const word of text.replace(/\*\//g, "*\\/").split(/\s+/).filter(Boolean)) {
+        if (line && line.length + word.length + 1 > width) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        lines.push(line);
+    return lines;
+}
+/**
+ * `/** text *\/`, with continuation lines under the opener: the format all five generators wrote
+ * for a field, byte for byte.
+ */
+export function docComment(text, indent = "    ") {
+    return `${indent}/** ${wrapLines(text, indent).join(`\n${indent} *  `)} */\n`;
+}
+/**
+ * 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 function typeNames(expression) {
+    const names = expression.match(/\b[A-Z][A-Za-z0-9_]*\b/g) ?? [];
+    return [...new Set(names)].filter((name) => !BUILTIN.has(name));
+}
+/** `send_message` → `sendMessage`. */
+export const camelCase = (name) => name.replace(/[_-](\w)/g, (_m, c) => c.toUpperCase());
+/** `send_message` → `SendMessage`. */
+export const pascalCase = (name) => {
+    const camel = camelCase(name);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACvC,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IACrC,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,QAAQ,QAAQ,CAAC,MAAM,mEAAmE,CAC3F,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,UAAU,CAAC,MAAoB;IACtC,OAAO,WAAW,IAAI,MAAM,CAAC;AAC/B,CAAC;AAED,kGAAkG;AAClG,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;IAC1B,SAAS;IACT,UAAU;IACV,OAAO;IACP,aAAa;IACb,SAAS;IACT,UAAU;IACV,YAAY;IACZ,UAAU;IACV,WAAW;CACZ,CAAC,CAAC;AAEH,0FAA0F;AAC1F,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC;IAC7B,OAAO;IACP,aAAa;IACb,SAAS;IACT,MAAM;IACN,YAAY;IACZ,MAAM;IACN,OAAO;IACP,SAAS;IACT,SAAS;IACT,WAAW;IACX,KAAK;IACL,aAAa;IACb,MAAM;IACN,YAAY;IACZ,SAAS;IACT,MAAM;IACN,SAAS;IACT,UAAU;IACV,eAAe;IACf,aAAa;IACb,aAAa;IACb,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,YAAY;IACZ,KAAK;IACL,KAAK;IACL,YAAY;IACZ,cAAc;IACd,WAAW;CACZ,CAAC,CAAC;AAEH,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,oFAAoF;AACpF,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAChE,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,MAA4B,EAAE,MAAM,GAAG,EAAE;IAC9D,IAAI,OAAO,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IACrE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;IACxD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrF,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;IACjD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3F,2FAA2F;IAC3F,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7E,yFAAyF;IACzF,wEAAwE;IACxE,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAE/E,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;YAC9B,uFAAuF;YACvF,oBAAoB;YACpB,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAClF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,GACR,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,KAAK;oBAC5D,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,QAAQ,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC;gBAClD,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC;YAChF,CAAC;YACD,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;YAC/E,sFAAsF;YACtF,sBAAsB;YACtB,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC;QAC5D,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,CAAC;YACjD,IAAI,MAAM;gBAAE,OAAO,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC;YAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;YAC9C,wEAAwE;YACxE,OAAO,QAAQ,CAAC,MAAM,CAAC;gBACrB,CAAC,CAAC,kBAAkB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG;gBAC7C,CAAC,CAAC,yBAAyB,CAAC;QAChC,CAAC;QACD;YACE,MAAM,IAAI,KAAK,CAAC,4CAA4C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1F,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,MAAkB,EAClB,MAAM,GAAG,MAAM,EACf,OAA0B,EAAE;IAE5B,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACtF,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACrD,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAS;QAClC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,WAAW,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACjF,IAAI,OAAO,WAAW,KAAK,QAAQ;YAAE,GAAG,IAAI,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC5E,8EAA8E;QAC9E,MAAM,GAAG,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC1E,GAAG,IAAI,GAAG,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;IACxF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,MAAkB,EAClB,OAA0B,EAAE;IAE5B,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,OAAO;QACL,MAAM,EAAE,oBAAoB,IAAI,OAAO,MAAM,KAAK;QAClD,QAAQ,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;KACxF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,MAAM,GAAG,MAAM;IACrD,MAAM,KAAK,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9E,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC;YAClD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,IAAI,GAAG,IAAI,CAAC;QACd,CAAC;;YAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;IACD,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAM,GAAG,MAAM;IACtD,OAAO,GAAG,MAAM,OAAO,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,MAAM,MAAM,CAAC,OAAO,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,yBAAyB,CAAC,IAAI,EAAE,CAAC;IAChE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,sCAAsC;AACtC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,IAAY,EAAU,EAAE,CAChD,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAEhE,sCAAsC;AACtC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAU,EAAE;IACjD,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC,CAAC"}

package/dist/write.d.ts

@@ -0,0 +1,29 @@
+/** The generated text for each file, by path: absolute, or relative to `root`. */
+export type GeneratedFiles = Readonly<Record<string, string>>;
+export interface WriteOptions {
+    /** What a relative path in `files` starts from, usually the repo root. Default: the working directory. */
+    root?: string;
+    /** Write nothing, and list the files that would change. */
+    check?: boolean;
+}
+/** Paths as `files` spells them, so a message can print them as they are. */
+export interface WriteResult {
+    /** Files that were missing or different and were written. Always empty when checking. */
+    written: string[];
+    /** Files that are missing or differ from what the API says today. Always empty when writing. */
+    stale: string[];
+}
+/**
+ * Formats each file with the prettier config that applies at its path, then writes it — or, with
+ * `check`, writes nothing and lists the files that would change.
+ *
+ * ```ts
+ * const { stale } = await writeGenerated(files, { root, 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;
+ * }
+ * ```
+ */
+export declare function writeGenerated(files: GeneratedFiles, { root, check }?: WriteOptions): Promise<WriteResult>;
+//# sourceMappingURL=write.d.ts.map

package/dist/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AAWA,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,0GAA0G;IAC1G,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gGAAgG;IAChG,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,EACrB,EAAE,IAAU,EAAE,KAAa,EAAE,GAAE,YAAiB,GAC/C,OAAO,CAAC,WAAW,CAAC,CAetB"}

package/dist/write.js

@@ -0,0 +1,52 @@
+/**
+ * Writing generated files, or proving the ones on disk are current.
+ *
+ * Every file goes through the repo's own prettier config first. The output is checked in and read
+ * by whoever opens the SDK, and formatting it here is also what keeps `format:check` and the
+ * generator's own check from ever disagreeing about one file.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { format, resolveConfig } from "prettier";
+/**
+ * Formats each file with the prettier config that applies at its path, then writes it — or, with
+ * `check`, writes nothing and lists the files that would change.
+ *
+ * ```ts
+ * const { stale } = await writeGenerated(files, { root, 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;
+ * }
+ * ```
+ */
+export async function writeGenerated(files, { root = ".", check = false } = {}) {
+    const result = { written: [], stale: [] };
+    for (const [name, text] of Object.entries(files)) {
+        const path = resolve(root, name);
+        const formatted = await format(text, { ...(await resolveConfig(path)), filepath: path });
+        if (readOrNull(path) === formatted)
+            continue;
+        if (check) {
+            result.stale.push(name);
+            continue;
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, formatted);
+        result.written.push(name);
+    }
+    return result;
+}
+function readOrNull(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        // Missing is stale. Anything else, such as a permission error, is not an answer to "is it
+        // current", so it throws.
+        if (err instanceof Error && "code" in err && err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+//# sourceMappingURL=write.js.map

package/dist/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAoBjD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAqB,EACrB,EAAE,IAAI,GAAG,GAAG,EAAE,KAAK,GAAG,KAAK,KAAmB,EAAE;IAEhD,MAAM,MAAM,GAAgB,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACvD,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACjC,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACzF,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC7C,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxB,SAAS;QACX,CAAC;QACD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC/B,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0FAA0F;QAC1F,0BAA0B;QAC1B,IAAI,GAAG,YAAY,KAAK,IAAI,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAChF,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@gusnips/sdkgen",
+  "version": "0.1.0",
+  "description": "The pieces of an SDK generator: copy your API's types with their comments, write a schema as a TypeScript type, and keep the output current.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Gustavo Salomé",
+  "homepage": "https://github.com/gusnips/serverkit/tree/main/sdkgen#readme",
+  "bugs": {
+    "url": "https://github.com/gusnips/serverkit/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "sdk",
+    "codegen",
+    "json-schema",
+    "typescript",
+    "zod"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "sync:docs": "cp ../LICENSE .",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build && bun run sync:docs",
+    "release:patch": "bun pm version patch && bun publish --access public",
+    "release:minor": "bun pm version minor && bun publish --access public",
+    "release:major": "bun pm version major && bun publish --access public"
+  },
+  "peerDependencies": {
+    "prettier": ">=3.4 <4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2",
+    "zod": "^4.4.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gusnips/serverkit.git",
+    "directory": "sdkgen"
+  }
+}

package/src/contract.test.ts

@@ -0,0 +1,201 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { blankCommentsAndStrings, liftContract } from "./contract.ts";
+
+function repo(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), "sdkgen-"));
+  for (const [name, text] of Object.entries(files)) writeFileSync(join(root, name), text);
+  return root;
+}
+
+const HTTP = `import { z } from "zod";
+
+/** Every code the API answers with. */
+export const ERROR_STATUS = {
+  VALIDATION_ERROR: 400,
+  NOT_FOUND: 404,
+} as const;
+
+export type ErrorCode = keyof typeof ERROR_STATUS;
+
+/**
+ * A refusal.
+ * The message is for a log; the code is for a program.
+ */
+export interface ApiError {
+  code: ErrorCode;
+  message: string;
+}
+
+const internal = 1;
+`;
+
+const DTO = `/** One message; see Status. */
+export interface MessageDto {
+  id: string;
+  /** Where it is; "Sent" means the server took it; not a type. */
+  status: MessageStatus;
+  sentAt: Date | null;
+}
+
+export const STATUSES = [
+  /** It's waiting; nothing has gone out. */
+  "queued",
+  "sent",
+  "failed",
+] as const;
+
+export type MessageStatus = (typeof STATUSES)[number];
+
+export type Page<T> = { items: T[]; next: string | null };
+
+export type ByStatus = { [K in MessageStatus]: number; };
+
+export function isSent(message: MessageDto): boolean {
+  return message.status === "sent";
+}
+`;
+
+describe("liftContract", () => {
+  const root = repo({ "http.ts": HTTP, "dto.ts": DTO });
+  const lift = (roots: string[], inlineTuples = false) =>
+    liftContract({ root, sources: ["http.ts", "dto.ts"], roots, inlineTuples });
+
+  it("copies a declaration with its comment, and what it mentions, in source order", () => {
+    const out = lift(["ApiError"]);
+    expect(out).toContain("/** Every code the API answers with. */\nexport const ERROR_STATUS");
+    expect(out).toContain("export type ErrorCode = keyof typeof ERROR_STATUS;");
+    expect(out).toContain(
+      " * A refusal.\n * The message is for a log; the code is for a program.\n */",
+    );
+    expect(out.indexOf("ERROR_STATUS =")).toBeLessThan(out.indexOf("interface ApiError"));
+    expect(out).not.toContain("internal");
+    expect(out).not.toContain("MessageDto");
+  });
+
+  it("does not read a property key as a type to find", () => {
+    // VALIDATION_ERROR and NOT_FOUND are keys of ERROR_STATUS; declared nowhere, they would throw.
+    expect(() => lift(["ERROR_STATUS"])).not.toThrow();
+  });
+
+  it("copies a tuple as it is written, its members' comments included", () => {
+    const out = lift(["MessageDto"]);
+    expect(out).toContain(
+      "export const STATUSES = [\n  /** It's waiting; nothing has gone out. */",
+    );
+    expect(out).toContain("export type MessageStatus = (typeof STATUSES)[number];");
+  });
+
+  it("can write a tuple's element type as its literal union, and leave the array behind", () => {
+    // The apostrophe in the member's comment is not a quote.
+    const out = lift(["MessageDto"], true);
+    expect(out).toContain('export type MessageStatus = "queued" | "sent" | "failed";');
+    expect(out).not.toContain("STATUSES");
+  });
+
+  it("ignores words in comments and strings, and a semicolon inside a mapped type", () => {
+    // "Status" and "Sent" in the prose are not types; the mapped type's `;` is inside braces.
+    const out = lift(["MessageDto", "ByStatus"]);
+    expect(out).toContain("export type ByStatus = { [K in MessageStatus]: number; };");
+  });
+
+  it("can keep export on the roots only", () => {
+    const out = lift(["ApiError"]).replace(/\n+/g, "\n");
+    expect(out).toContain("export const ERROR_STATUS");
+    const quiet = liftContract({
+      root,
+      sources: ["http.ts", "dto.ts"],
+      roots: ["ApiError"],
+      exportOnlyRoots: true,
+    });
+    expect(quiet).toContain("/** Every code the API answers with. */\nconst ERROR_STATUS = {");
+    expect(quiet).toContain("\ntype ErrorCode = keyof typeof ERROR_STATUS;");
+    expect(quiet).toContain("\nexport interface ApiError {");
+  });
+
+  it("copies an exported function whole", () => {
+    expect(lift(["isSent"])).toContain('  return message.status === "sent";\n}');
+  });
+
+  it("names what it could not find, and where it looked", () => {
+    expect(() => lift(["Missing"])).toThrow(
+      /No declaration found for Missing\. Export it from one of:\n {2}http\.ts\n {2}dto\.ts/,
+    );
+  });
+
+  it("unescapes a quoted member before writing it", () => {
+    const quoted = repo({
+      "a.ts": `export const KINDS = ["a", 'b\\'c'] as const;\n\nexport type Kind = (typeof KINDS)[number];\n`,
+    });
+    expect(
+      liftContract({ root: quoted, sources: ["a.ts"], roots: ["Kind"], inlineTuples: true }),
+    ).toContain(`export type Kind = "a" | "b'c";`);
+  });
+
+  it("refuses a member escape it cannot read, rather than writing a wrong member", () => {
+    const escaped = repo({
+      "a.ts": `export const KINDS = ["a\\nb"] as const;\n\nexport type Kind = (typeof KINDS)[number];\n`,
+    });
+    expect(() =>
+      liftContract({ root: escaped, sources: ["a.ts"], roots: ["Kind"], inlineTuples: true }),
+    ).toThrow(/KINDS has a member with an escape this cannot read: "a\\nb"/);
+  });
+
+  it("refuses a tuple it cannot read as string literals", () => {
+    const odd = repo({
+      "a.ts": `export const SIZES = [1, 2] as const;\n\nexport type Size = (typeof SIZES)[number];\n`,
+    });
+    expect(() =>
+      liftContract({ root: odd, sources: ["a.ts"], roots: ["Size"], inlineTuples: true }),
+    ).toThrow(/SIZES must be a tuple of string literals/);
+  });
+
+  it("keeps every later declaration in place after an escaped newline", () => {
+    const tricky = repo({
+      "a.ts": [
+        'export const HELP = "one \\',
+        'two";',
+        "",
+        "/** The plan. */",
+        "export interface Plan {",
+        "  id: string;",
+        "}",
+        "",
+      ].join("\n"),
+    });
+    expect(liftContract({ root: tricky, sources: ["a.ts"], roots: ["Plan"] })).toContain(
+      "/** The plan. */\nexport interface Plan {\n  id: string;\n}",
+    );
+  });
+  it("ends a one-line interface on its own line", () => {
+    const flat = repo({
+      "a.ts": "export interface Empty {}\n\nexport interface Plan {\n  id: string;\n}\n",
+    });
+    const out = liftContract({ root: flat, sources: ["a.ts"], roots: ["Empty"] });
+    expect(out).toContain("export interface Empty {}");
+    expect(out).not.toContain("Plan");
+  });
+});
+
+describe("blankCommentsAndStrings", () => {
+  it("keeps every line and every column", () => {
+    const source = 'const a = "x;\\"y"; // Type\n/* Also\n a Type */ const b = `t\\\nu`;\n';
+    const clean = blankCommentsAndStrings(source);
+    expect(clean.length).toBe(source.length);
+    expect(clean.split("\n").length).toBe(source.split("\n").length);
+    expect(clean).not.toMatch(/Type|x;|y/);
+    expect(clean).toContain("const b =");
+  });
+
+  it("ends a line comment at its newline, even after a backslash", () => {
+    expect(blankCommentsAndStrings("// C:\\\nexport type X = 1;")).toBe(
+      "      \nexport type X = 1;",
+    );
+  });
+
+  it("does not close a comment on the star that opened it", () => {
+    expect(blankCommentsAndStrings("/*/ Type */ x")).toBe("            x");
+  });
+});