frappe-codegen 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+import { FrappeClient } from 'frappe-js-client';
+
+/**
+ * @module config
+ * @description Loads `frappe-codegen.config.json` (no secrets). CLI flags and FRAPPE_* env override.
+ */
+declare const DEFAULT_CONFIG_NAME = "frappe-codegen.config.json";
+interface CodegenFileConfig {
+    url?: string;
+    out?: string;
+    includeHidden?: boolean;
+    followTables?: boolean;
+    doctypes?: string[];
+    modules?: string[];
+}
+interface ResolvedCodegenConfig {
+    url?: string;
+    out: string;
+    includeHidden: boolean;
+    followTables: boolean;
+    doctypes: string[];
+    modules: string[];
+    apiKey?: string;
+    apiSecret?: string;
+    dryRun: boolean;
+    emitDocTypeMap: boolean;
+    includeLabels: boolean;
+}
+declare function loadConfigFile(path: string): CodegenFileConfig;
+declare function findDefaultConfigPath(cwd?: string): string | undefined;
+interface CliOverlay {
+    url?: string;
+    out?: string;
+    includeHidden?: boolean;
+    followTables?: boolean;
+    doctypes?: string[];
+    modules?: string[];
+    apiKey?: string;
+    apiSecret?: string;
+    dryRun?: boolean;
+    emitDocTypeMap?: boolean;
+    includeLabels?: boolean;
+    configPath?: string;
+}
+/** Merge file config, then env, then CLI flags (last wins). */
+declare function mergeConfig(file: CodegenFileConfig | undefined, overlay: CliOverlay): ResolvedCodegenConfig;
+
+/**
+ * @module metadata
+ * @description Fetches DocType metadata from a live Frappe site via `frappe-js-client`'s
+ * `db.getMeta()` (v2-only — `GET /api/v2/doctype/{doctype}/meta`) and normalizes it into the
+ * small shape `generate.ts` needs.
+ */
+
+interface DocField {
+    fieldname: string;
+    fieldtype: string;
+    label?: string;
+    options?: string;
+    reqd?: 0 | 1;
+    hidden?: 0 | 1;
+    description?: string;
+    is_virtual?: 0 | 1;
+}
+interface DocTypeMeta {
+    name: string;
+    fields: DocField[];
+    istable?: 0 | 1;
+    /** True for the small set of built-in single-instance DocTypes (e.g. `System Settings`). */
+    issingle?: 0 | 1;
+}
+/** Fetches and normalizes the metadata for one DocType. Requires a v2 client. */
+declare function fetchDocTypeMeta(client: FrappeClient, doctype: string): Promise<DocTypeMeta>;
+/** Fetches metadata for several DocTypes with a small concurrency pool. */
+declare function fetchDocTypeMetas(client: FrappeClient, doctypes: readonly string[]): Promise<DocTypeMeta[]>;
+
+/**
+ * @module generate
+ * @description Turns normalized `DocTypeMeta` into TypeScript source: one `FrappeDoc<...>`
+ * type per DocType, an insert alias, plus `GeneratedDocTypes` / `GeneratedInserts` maps.
+ */
+
+interface GenerateOptions {
+    /**
+     * Include fields marked `hidden` in the meta. Default `false`.
+     * Frappe `hidden` is form visibility (e.g. Reminder `user` / `notified`), not "absent from the document".
+     */
+    includeHidden?: boolean;
+    /** Emit a `/** label *\/` doc comment above each field. Default `true`. */
+    includeLabels?: boolean;
+    /** Emit the GeneratedDocTypes / GeneratedInserts lookup maps. Default `true`. */
+    emitDocTypeMap?: boolean;
+}
+/** `Sales Order` -> `SalesOrder`. Not injective for pathological names — collisions are rejected. */
+declare function toInterfaceName(doctype: string): string;
+declare function assertUniqueInterfaceNames(metas: readonly DocTypeMeta[]): void;
+/** Generates one read type plus its insert alias for a single DocType. */
+declare function generateInterface(meta: DocTypeMeta, allMetas?: readonly DocTypeMeta[], opts?: GenerateOptions): string;
+/** Generates a full, self-contained `.ts` module. */
+declare function generateModule(metas: readonly DocTypeMeta[], opts?: GenerateOptions): string;
+
+/**
+ * @module resolve
+ * @description Collect DocType names from flags/config/modules and follow Table children.
+ */
+
+declare function resolveDocTypes(client: FrappeClient, seeds: {
+    doctypes: readonly string[];
+    modules: readonly string[];
+}): Promise<string[]>;
+/** Fetch seed metas, then recursively fetch Table / Table MultiSelect children. */
+declare function followChildTables(client: FrappeClient, seeds: readonly DocTypeMeta[]): Promise<DocTypeMeta[]>;
+declare function fetchWithOptionalFollow(client: FrappeClient, doctypes: readonly string[], followTables: boolean): Promise<DocTypeMeta[]>;
+
+export { type CliOverlay, type CodegenFileConfig, DEFAULT_CONFIG_NAME, type DocField, type DocTypeMeta, type GenerateOptions, type ResolvedCodegenConfig, assertUniqueInterfaceNames, fetchDocTypeMeta, fetchDocTypeMetas, fetchWithOptionalFollow, findDefaultConfigPath, followChildTables, generateInterface, generateModule, loadConfigFile, mergeConfig, resolveDocTypes, toInterfaceName };

package/dist/index.js

@@ -0,0 +1,387 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+// src/config.ts
+var DEFAULT_CONFIG_NAME = "frappe-codegen.config.json";
+function loadConfigFile(path) {
+  const raw = fs.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 = path.resolve(cwd, DEFAULT_CONFIG_NAME);
+  return fs.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);
+}
+
+exports.DEFAULT_CONFIG_NAME = DEFAULT_CONFIG_NAME;
+exports.assertUniqueInterfaceNames = assertUniqueInterfaceNames;
+exports.fetchDocTypeMeta = fetchDocTypeMeta;
+exports.fetchDocTypeMetas = fetchDocTypeMetas;
+exports.fetchWithOptionalFollow = fetchWithOptionalFollow;
+exports.findDefaultConfigPath = findDefaultConfigPath;
+exports.followChildTables = followChildTables;
+exports.generateInterface = generateInterface;
+exports.generateModule = generateModule;
+exports.loadConfigFile = loadConfigFile;
+exports.mergeConfig = mergeConfig;
+exports.resolveDocTypes = resolveDocTypes;
+exports.toInterfaceName = toInterfaceName;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map