frappe-codegen 1.0.0

package/dist/index.mjs

@@ -0,0 +1,373 @@
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+// src/config.ts
+var DEFAULT_CONFIG_NAME = "frappe-codegen.config.json";
+function loadConfigFile(path) {
+  const raw = readFileSync(path, "utf8");
+  const parsed = JSON.parse(raw);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`frappe-codegen: ${path} must be a JSON object`);
+  }
+  const obj = parsed;
+  if ("apiKey" in obj || "apiSecret" in obj || "api-key" in obj) {
+    throw new Error("frappe-codegen: do not put API secrets in the config file; use --api-key / FRAPPE_API_KEY");
+  }
+  return {
+    url: typeof obj.url === "string" ? obj.url : void 0,
+    out: typeof obj.out === "string" ? obj.out : void 0,
+    includeHidden: typeof obj.includeHidden === "boolean" ? obj.includeHidden : void 0,
+    followTables: typeof obj.followTables === "boolean" ? obj.followTables : void 0,
+    doctypes: Array.isArray(obj.doctypes) ? obj.doctypes.filter((d) => typeof d === "string") : void 0,
+    modules: Array.isArray(obj.modules) ? obj.modules.filter((d) => typeof d === "string") : void 0
+  };
+}
+function findDefaultConfigPath(cwd = process.cwd()) {
+  const candidate = resolve(cwd, DEFAULT_CONFIG_NAME);
+  return existsSync(candidate) ? candidate : void 0;
+}
+function envString(name) {
+  const value = process.env[name];
+  return value && value.length > 0 ? value : void 0;
+}
+function mergeConfig(file, overlay) {
+  const envUrl = envString("FRAPPE_URL");
+  const envKey = envString("FRAPPE_API_KEY");
+  const envSecret = envString("FRAPPE_API_SECRET");
+  const doctypes = [...file?.doctypes ?? [], ...overlay.doctypes ?? []];
+  const modules = [...file?.modules ?? [], ...overlay.modules ?? []];
+  return {
+    url: overlay.url ?? envUrl ?? file?.url,
+    out: overlay.out ?? file?.out ?? "./frappe-types.generated.ts",
+    includeHidden: overlay.includeHidden ?? file?.includeHidden ?? false,
+    followTables: overlay.followTables ?? file?.followTables ?? true,
+    doctypes: [...new Set(doctypes)],
+    modules: [...new Set(modules)],
+    apiKey: overlay.apiKey ?? envKey,
+    apiSecret: overlay.apiSecret ?? envSecret,
+    dryRun: overlay.dryRun ?? false,
+    emitDocTypeMap: overlay.emitDocTypeMap ?? true,
+    includeLabels: overlay.includeLabels ?? true
+  };
+}
+
+// src/field-types.ts
+var NUMBER_FIELD_TYPES = /* @__PURE__ */ new Set(["Int", "Float", "Currency", "Percent", "Rating", "Duration"]);
+var STRING_FIELD_TYPES = /* @__PURE__ */ new Set([
+  "Data",
+  "Small Text",
+  "Text",
+  "Long Text",
+  "Text Editor",
+  "Code",
+  "HTML Editor",
+  "Markdown Editor",
+  "Password",
+  "Read Only",
+  "Dynamic Link",
+  "Date",
+  "Datetime",
+  "Time",
+  "Attach",
+  "Attach Image",
+  "Barcode",
+  "Color",
+  "Signature",
+  "Phone",
+  "Icon",
+  "Autocomplete"
+]);
+var UNKNOWN_FIELD_TYPES = /* @__PURE__ */ new Set(["JSON", "Geolocation"]);
+var LAYOUT_FIELD_TYPES = /* @__PURE__ */ new Set([
+  "Section Break",
+  "Column Break",
+  "Tab Break",
+  "Fold",
+  "Heading",
+  "Button",
+  "HTML",
+  "Image"
+]);
+function isTableFieldType(fieldtype) {
+  return fieldtype === "Table" || fieldtype === "Table MultiSelect";
+}
+function selectLiterals(options) {
+  if (!options) return [];
+  return options.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map(selectValue);
+}
+function selectValue(line) {
+  const colon = line.indexOf(":");
+  const comma = line.indexOf(",");
+  if (colon > 0 && (comma < 0 || colon < comma)) {
+    return line.slice(0, colon).trim();
+  }
+  if (comma > 0) {
+    return line.slice(0, comma).trim();
+  }
+  return line;
+}
+function mapFieldType(field, ctx = {}) {
+  const { fieldtype, options } = field;
+  if (fieldtype === "Check") {
+    return "0 | 1";
+  }
+  if (fieldtype === "Select") {
+    const literals = selectLiterals(options);
+    if (literals.length === 0) {
+      return "string";
+    }
+    return literals.map((literal) => JSON.stringify(literal)).join(" | ");
+  }
+  if (isTableFieldType(fieldtype)) {
+    const childInterface = options ? ctx.resolveChildInterfaceName?.(options) : void 0;
+    return childInterface ? `${childInterface}[]` : "FrappeDoc<Record<string, unknown>>[]";
+  }
+  if (fieldtype === "Link") {
+    if (options && options.trim().length > 0) {
+      return `Link<${JSON.stringify(options.trim())}>`;
+    }
+    return "string";
+  }
+  if (NUMBER_FIELD_TYPES.has(fieldtype)) {
+    return "number";
+  }
+  if (UNKNOWN_FIELD_TYPES.has(fieldtype)) {
+    return "unknown";
+  }
+  if (STRING_FIELD_TYPES.has(fieldtype)) {
+    return "string";
+  }
+  return "unknown";
+}
+
+// src/generate.ts
+var DEFAULTS = {
+  includeHidden: false,
+  includeLabels: true,
+  emitDocTypeMap: true
+};
+function toInterfaceName(doctype) {
+  const cleaned = doctype.replace(/[^a-zA-Z0-9 ]/g, " ").split(" ").filter(Boolean).map((word) => word[0].toUpperCase() + word.slice(1)).join("");
+  return /^[A-Za-z_]/.test(cleaned) ? cleaned : `_${cleaned}`;
+}
+function assertUniqueInterfaceNames(metas) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const meta of metas) {
+    const id = toInterfaceName(meta.name);
+    const list = byName.get(id) ?? [];
+    list.push(meta.name);
+    byName.set(id, list);
+  }
+  const collisions = [...byName.entries()].filter(([, names]) => names.length > 1);
+  if (collisions.length === 0) return;
+  const detail = collisions.map(([id, names]) => `${id} <= ${names.map((n) => JSON.stringify(n)).join(", ")}`).join("; ");
+  throw new Error(`frappe-codegen: interface name collision: ${detail}`);
+}
+function shouldEmitField(field, options) {
+  if (LAYOUT_FIELD_TYPES.has(field.fieldtype)) return false;
+  if (field.is_virtual) return false;
+  if (field.hidden && !options.includeHidden) return false;
+  if (!field.fieldname) return false;
+  return true;
+}
+function isValidIdentifier(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+function propertyKey(fieldname) {
+  return isValidIdentifier(fieldname) ? fieldname : JSON.stringify(fieldname);
+}
+function isCheckRequiredOnRead(field) {
+  return field.fieldtype === "Check";
+}
+function fieldComment(field, includeLabels) {
+  if (field.fieldtype === "Password") {
+    const secret = "GET usually returns empty or masked (`*`); use db.getPassword to read the secret.";
+    if (includeLabels && field.label) {
+      return `    /** ${field.label.replace(/\*\//g, "*\u2215")} \u2014 ${secret} */
+`;
+    }
+    return `    /** ${secret} */
+`;
+  }
+  if (includeLabels && field.label) {
+    return `    /** ${field.label.replace(/\*\//g, "*\u2215")} */
+`;
+  }
+  return "";
+}
+function generateInterface(meta, allMetas = [meta], opts = {}) {
+  const options = { ...DEFAULTS, ...opts };
+  const interfaceName = toInterfaceName(meta.name);
+  const knownDoctypes = new Set(allMetas.map((m) => m.name));
+  const emitted = meta.fields.filter((field) => shouldEmitField(field, options));
+  const checkKeys = emitted.filter((field) => field.fieldtype === "Check").map((field) => field.fieldname);
+  const fieldLines = emitted.map((field) => {
+    const optional = field.reqd || isCheckRequiredOnRead(field) ? "" : "?";
+    const type = mapFieldType(field, {
+      resolveChildInterfaceName: (childDoctype) => knownDoctypes.has(childDoctype) ? toInterfaceName(childDoctype) : void 0
+    });
+    return `${fieldComment(field, options.includeLabels)}    ${propertyKey(field.fieldname)}${optional}: ${type}`;
+  });
+  const doctypeLine = `    doctype: ${JSON.stringify(meta.name)}`;
+  const inner = [doctypeLine, ...fieldLines].join("\n");
+  const body = `{
+${inner}
+}`;
+  const insertAlias = checkKeys.length === 0 ? `export type ${interfaceName}Insert = FrappeInsert<${interfaceName}>` : `export type ${interfaceName}Insert = FrappeInsert<Omit<${interfaceName}, ${checkKeys.map((k) => JSON.stringify(k)).join(" | ")}> & Partial<Pick<${interfaceName}, ${checkKeys.map((k) => JSON.stringify(k)).join(" | ")}>>>`;
+  return [
+    `/** Generated from DocType \`${meta.name}\`. Do not edit by hand \u2014 regenerate with \`frappe-codegen --help\`. */`,
+    `export type ${interfaceName} = FrappeDoc<${body}>`,
+    insertAlias
+  ].join("\n");
+}
+function collectImports(source) {
+  const names = ["FrappeDoc", "FrappeInsert"];
+  if (source.includes("Link<")) {
+    names.push("Link");
+  }
+  return `import type { ${names.join(", ")} } from 'frappe-js-client/types'`;
+}
+function generateModule(metas, opts = {}) {
+  const options = { ...DEFAULTS, ...opts };
+  assertUniqueInterfaceNames(metas);
+  const interfaces = metas.map((meta) => generateInterface(meta, metas, options)).join("\n\n");
+  const header = [
+    "/**",
+    " * This file was generated by frappe-codegen. Do not edit by hand \u2014",
+    ' * regenerate it instead: `frappe-codegen --url <site> --doctype "..." --out <this file>`.',
+    " */",
+    collectImports(interfaces),
+    ""
+  ].join("\n");
+  if (!options.emitDocTypeMap) {
+    return `${header}
+${interfaces}
+`;
+  }
+  const mapEntries = metas.map((meta) => `    ${JSON.stringify(meta.name)}: ${toInterfaceName(meta.name)}`).join("\n");
+  const insertEntries = metas.map((meta) => `    ${JSON.stringify(meta.name)}: ${toInterfaceName(meta.name)}Insert`).join("\n");
+  const map = [
+    "",
+    "/** Maps a DocType name to its generated read type. Pass as `createFrappeClient<GeneratedDocTypes>(...)`. */",
+    "export interface GeneratedDocTypes {",
+    mapEntries,
+    "}",
+    "",
+    "/** Maps a DocType name to its insert payload type. */",
+    "export interface GeneratedInserts {",
+    insertEntries,
+    "}"
+  ].join("\n");
+  return `${header}
+${interfaces}
+${map}
+`;
+}
+
+// src/metadata.ts
+async function fetchDocTypeMeta(client, doctype) {
+  try {
+    const raw = await client.db.getMeta(doctype);
+    return {
+      name: raw.name ?? doctype,
+      fields: raw.fields ?? [],
+      istable: raw.istable,
+      issingle: raw.issingle
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const name = error instanceof Error ? error.name : "";
+    if (name === "FeatureNotSupportedError" || name === "NotFoundError") {
+      throw new Error(
+        `frappe-codegen requires Frappe v15+ REST API v2 (GET /api/v2/doctype/{doctype}/meta). Could not fetch metadata for ${JSON.stringify(doctype)}: ${message}`,
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
+var FETCH_CONCURRENCY = 4;
+async function mapPool(items, concurrency, mapper) {
+  if (items.length === 0) return [];
+  const results = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      results[index] = await mapper(items[index]);
+    }
+  }
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}
+async function fetchDocTypeMetas(client, doctypes) {
+  return mapPool(doctypes, FETCH_CONCURRENCY, (doctype) => fetchDocTypeMeta(client, doctype));
+}
+
+// src/resolve.ts
+async function listDocTypesInModule(client, moduleName) {
+  const names = [];
+  for await (const row of client.db.paginate("DocType", {
+    filters: [["module", "=", moduleName]],
+    fields: ["name"],
+    limit: 100
+  })) {
+    if (typeof row.name === "string") {
+      names.push(row.name);
+    }
+  }
+  return names;
+}
+async function resolveDocTypes(client, seeds) {
+  const names = new Set(seeds.doctypes);
+  for (const moduleName of seeds.modules) {
+    for (const name of await listDocTypesInModule(client, moduleName)) {
+      names.add(name);
+    }
+  }
+  return [...names];
+}
+function childTableDoctypes(meta) {
+  const children = [];
+  for (const field of meta.fields) {
+    if (isTableFieldType(field.fieldtype) && field.options) {
+      children.push(field.options);
+    }
+  }
+  return children;
+}
+async function followChildTables(client, seeds) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const meta of seeds) {
+    byName.set(meta.name, meta);
+  }
+  const pending = /* @__PURE__ */ new Set();
+  for (const meta of seeds) {
+    for (const child of childTableDoctypes(meta)) {
+      if (!byName.has(child)) pending.add(child);
+    }
+  }
+  while (pending.size > 0) {
+    const batch = [...pending];
+    pending.clear();
+    const fetched = await fetchDocTypeMetas(client, batch);
+    for (const meta of fetched) {
+      byName.set(meta.name, meta);
+      for (const child of childTableDoctypes(meta)) {
+        if (!byName.has(child)) pending.add(child);
+      }
+    }
+  }
+  return [...byName.values()];
+}
+async function fetchWithOptionalFollow(client, doctypes, followTables) {
+  const seeds = await fetchDocTypeMetas(client, doctypes);
+  if (!followTables) return seeds;
+  return followChildTables(client, seeds);
+}
+
+export { DEFAULT_CONFIG_NAME, assertUniqueInterfaceNames, fetchDocTypeMeta, fetchDocTypeMetas, fetchWithOptionalFollow, findDefaultConfigPath, followChildTables, generateInterface, generateModule, loadConfigFile, mergeConfig, resolveDocTypes, toInterfaceName };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "frappe-codegen",
+  "version": "1.0.0",
+  "description": "CLI that reads a live Frappe site's DocType metadata and emits typed TypeScript interfaces for frappe-js-client.",
+  "author": "Dhia A. Shalabi <dhia.shalabi@gmail.com>",
+  "license": "MIT",
+  "type": "commonjs",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "frappe",
+    "frappe-framework",
+    "codegen",
+    "typescript",
+    "cli"
+  ],
+  "homepage": "https://dhiashalabi.github.io/frappe-js-client/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dhiashalabi/frappe-js-client.git",
+    "directory": "packages/codegen"
+  },
+  "bugs": {
+    "url": "https://github.com/dhiashalabi/frappe-js-client/issues"
+  },
+  "bin": {
+    "frappe-codegen": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "frappe-js-client": "^3.3.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.4.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "eslint": "^10.10.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
+    "globals": "^17.12.0",
+    "publint": "^0.3.24",
+    "tsup": "^8.5.1",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm clean && tsup && node scripts/verify-dist.mjs",
+    "codegen": "node ./dist/cli.js",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "publint": "publint",
+    "attw": "attw --pack . --profile node16",
+    "gate": "pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm publint && pnpm attw"
+  }
+}