@ic-reactor/codegen 0.1.0

package/dist/index.js

@@ -0,0 +1,489 @@
+// src/naming.ts
+import { camelCase, pascalCase } from "change-case";
+function toPascalCase(str) {
+  return pascalCase(str);
+}
+function toCamelCase(str) {
+  return camelCase(str);
+}
+function getHookFileName(methodName, hookType) {
+  const camelMethod = toCamelCase(methodName);
+  const pascalType = toPascalCase(hookType);
+  return `${camelMethod}${pascalType}.ts`;
+}
+function getHookExportName(methodName, hookType) {
+  const camelMethod = toCamelCase(methodName);
+  const pascalType = toPascalCase(hookType);
+  return `${camelMethod}${pascalType}`;
+}
+function getReactHookName(methodName, hookType) {
+  const pascalMethod = toPascalCase(methodName);
+  const pascalType = toPascalCase(hookType);
+  return `use${pascalMethod}${pascalType}`;
+}
+function getReactorName(canisterName) {
+  return `${toCamelCase(canisterName)}Reactor`;
+}
+function getServiceTypeName(canisterName) {
+  return `${toPascalCase(canisterName)}Service`;
+}
+
+// src/did.ts
+import fs from "fs";
+function parseDIDFile(didFilePath) {
+  if (!fs.existsSync(didFilePath)) {
+    throw new Error(`DID file not found: ${didFilePath}`);
+  }
+  const content = fs.readFileSync(didFilePath, "utf-8");
+  return extractMethods(content);
+}
+function extractMethods(didContent) {
+  const methods = [];
+  const cleanContent = didContent.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+  const methodRegex = /([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(?:func\s*)?\(([^)]*)\)\s*->\s*\(([^)]*)\)\s*(query|composite_query)?/g;
+  let match;
+  while ((match = methodRegex.exec(cleanContent)) !== null) {
+    const name = match[1];
+    const args = match[2].trim();
+    const returnType = match[3].trim();
+    const queryAnnotation = match[4];
+    const isQuery = queryAnnotation === "query" || queryAnnotation === "composite_query";
+    methods.push({
+      name,
+      type: isQuery ? "query" : "mutation",
+      hasArgs: args.length > 0 && args !== "",
+      argsDescription: args || void 0,
+      returnDescription: returnType || void 0
+    });
+  }
+  return methods;
+}
+function getMethodsByType(methods, type) {
+  return methods.filter((m) => m.type === type);
+}
+function formatMethodForDisplay(method) {
+  const typeLabel = method.type === "query" ? "query" : "update";
+  const argsLabel = method.hasArgs ? "with args" : "no args";
+  return `${method.name} (${typeLabel}, ${argsLabel})`;
+}
+
+// src/bindgen.ts
+import { generate } from "@icp-sdk/bindgen/core";
+import path from "path";
+import fs2 from "fs";
+async function generateDeclarations(options) {
+  const { didFile, outDir } = options;
+  if (!fs2.existsSync(didFile)) {
+    return {
+      success: false,
+      declarationsDir: "",
+      error: `DID file not found: ${didFile}`
+    };
+  }
+  const declarationsDir = path.join(outDir, "declarations");
+  try {
+    if (!fs2.existsSync(outDir)) {
+      fs2.mkdirSync(outDir, { recursive: true });
+    }
+    if (fs2.existsSync(declarationsDir)) {
+      fs2.rmSync(declarationsDir, { recursive: true, force: true });
+    }
+    fs2.mkdirSync(declarationsDir, { recursive: true });
+    await generate({
+      didFile,
+      outDir,
+      // Pass the parent directory; bindgen appends "declarations"
+      output: {
+        actor: {
+          disabled: true
+          // We don't need actor creation, we use Reactor
+        },
+        force: true
+        // Overwrite existing files
+      }
+    });
+    return {
+      success: true,
+      declarationsDir
+    };
+  } catch (error) {
+    return {
+      success: false,
+      declarationsDir,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function declarationsExist(outDir, canisterName) {
+  const declarationsDir = path.join(outDir, "declarations");
+  const didTsPath = path.join(declarationsDir, `${canisterName}.did.ts`);
+  return fs2.existsSync(didTsPath);
+}
+function saveCandidFile(candidSource, outDir, canisterName) {
+  const candidDir = path.join(outDir, "candid");
+  if (!fs2.existsSync(candidDir)) {
+    fs2.mkdirSync(candidDir, { recursive: true });
+  }
+  const candidPath = path.join(candidDir, `${canisterName}.did`);
+  fs2.writeFileSync(candidPath, candidSource);
+  return candidPath;
+}
+
+// src/templates/reactor.ts
+import path2 from "path";
+function generateReactorFile(options) {
+  const {
+    canisterName,
+    canisterConfig,
+    globalClientManagerPath,
+    hasDeclarations = true,
+    advanced = false,
+    didContent
+  } = options;
+  const pascalName = toPascalCase(canisterName);
+  const reactorName = getReactorName(canisterName);
+  const serviceName = getServiceTypeName(canisterName);
+  const reactorType = canisterConfig.useDisplayReactor !== false ? "DisplayReactor" : "Reactor";
+  const clientManagerPath = canisterConfig.clientManagerPath ?? globalClientManagerPath ?? "../../lib/client";
+  const didFileName = path2.basename(canisterConfig.didFile);
+  const declarationsPath = `./declarations/${didFileName}`;
+  const vars = {
+    canisterName,
+    pascalName,
+    reactorName,
+    serviceName,
+    reactorType,
+    clientManagerPath,
+    declarationsPath,
+    useDisplayReactor: canisterConfig.useDisplayReactor !== false
+  };
+  if (!hasDeclarations) {
+    return generateFallbackReactorFile(vars);
+  }
+  if (advanced && didContent) {
+    return generateAdvancedReactorFile(vars, didContent);
+  }
+  return generateSimpleReactorFile(vars);
+}
+function reactorInstance(vars) {
+  const {
+    pascalName,
+    reactorName,
+    serviceName,
+    reactorType,
+    canisterName,
+    useDisplayReactor
+  } = vars;
+  return `/**
+ * ${pascalName} Reactor \u2014 ${useDisplayReactor ? "Display" : "Candid"} mode.
+ * ${useDisplayReactor ? "Automatically converts bigint \u2192 string, Principal \u2192 string, etc." : "Uses raw Candid types."}
+ */
+export const ${reactorName} = new ${reactorType}<${serviceName}>({
+  clientManager,
+  idlFactory,
+  name: "${canisterName}",
+})`;
+}
+function actorHooks(vars) {
+  const { pascalName, reactorName } = vars;
+  return `const {
+  useActorQuery: use${pascalName}Query,
+  useActorSuspenseQuery: use${pascalName}SuspenseQuery,
+  useActorInfiniteQuery: use${pascalName}InfiniteQuery,
+  useActorSuspenseInfiniteQuery: use${pascalName}SuspenseInfiniteQuery,
+  useActorMutation: use${pascalName}Mutation,
+  useActorMethod: use${pascalName}Method,
+} = createActorHooks(${reactorName})
+
+export {
+  use${pascalName}Query,
+  use${pascalName}SuspenseQuery,
+  use${pascalName}InfiniteQuery,
+  use${pascalName}SuspenseInfiniteQuery,
+  use${pascalName}Mutation,
+  use${pascalName}Method,
+}`;
+}
+function generateSimpleReactorFile(vars) {
+  const {
+    pascalName,
+    reactorType,
+    clientManagerPath,
+    declarationsPath,
+    serviceName
+  } = vars;
+  return `/**
+ * ${pascalName} Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen
+ */
+
+import { ${reactorType}, createActorHooks } from "@ic-reactor/react"
+import { clientManager } from "${clientManagerPath}"
+import { idlFactory, type _SERVICE } from "${declarationsPath}"
+
+export type ${serviceName} = _SERVICE
+
+${reactorInstance(vars)}
+
+${actorHooks(vars)}
+
+export { idlFactory }
+`;
+}
+function generateAdvancedReactorFile(vars, didContent) {
+  const {
+    pascalName,
+    reactorName,
+    serviceName,
+    reactorType,
+    clientManagerPath,
+    declarationsPath
+  } = vars;
+  const methods = extractMethods(didContent);
+  const hasQueryWithoutArgs = methods.some(
+    (m) => m.type === "query" && !m.hasArgs
+  );
+  const hasMutationWithoutArgs = methods.some(
+    (m) => m.type === "mutation" && !m.hasArgs
+  );
+  const extraImports = [];
+  if (hasQueryWithoutArgs) extraImports.push("createQuery");
+  if (hasMutationWithoutArgs) extraImports.push("createMutation");
+  const perMethodHooks = methods.map(({ name, type, hasArgs }) => {
+    const camelMethod = toCamelCase(name);
+    if (type === "query") {
+      if (!hasArgs) {
+        return `
+export const ${camelMethod}Query = createQuery(${reactorName}, {
+  functionName: "${name}",
+})`;
+      }
+      return "";
+    } else {
+      if (!hasArgs) {
+        return `
+export const ${camelMethod}Mutation = createMutation(${reactorName}, {
+  functionName: "${name}",
+})`;
+      }
+      return "";
+    }
+  }).filter(Boolean);
+  return `/**
+ * ${pascalName} Reactor (Advanced)
+ *
+ * Auto-generated by @ic-reactor/codegen
+ * Includes reactor instance, actor hooks, and per-method static hooks.
+ */
+
+import {
+  ${reactorType},
+  createActorHooks,${extraImports.length > 0 ? "\n  " + extraImports.join(",\n  ") + "," : ""}
+} from "@ic-reactor/react"
+import { clientManager } from "${clientManagerPath}"
+import { idlFactory, type _SERVICE } from "${declarationsPath}"
+
+type ${serviceName} = _SERVICE
+
+${reactorInstance(vars)}
+
+${actorHooks(vars)}
+${perMethodHooks.length > 0 ? `
+// Per-method static hooks (no-args methods only)
+${perMethodHooks.join("\n")}
+` : ""}
+export { idlFactory }
+export type { ${serviceName} }
+`;
+}
+function generateFallbackReactorFile(vars) {
+  const {
+    canisterName,
+    pascalName,
+    serviceName,
+    reactorType,
+    clientManagerPath,
+    declarationsPath
+  } = vars;
+  return `/**
+ * ${pascalName} Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * \u26A0\uFE0F Declarations were not generated. Run:
+ *   npx @icp-sdk/bindgen --input <path-to-did> --output ./${canisterName}/declarations
+ * Then uncomment the import below and remove the fallback type.
+ */
+
+import { ${reactorType}, createActorHooks } from "@ic-reactor/react"
+import { clientManager } from "${clientManagerPath}"
+
+// TODO: Uncomment after generating declarations:
+// import { idlFactory, type _SERVICE as ${serviceName} } from "${declarationsPath}"
+
+// Fallback \u2014 replace with generated types
+type ${serviceName} = Record<string, (...args: unknown[]) => Promise<unknown>>
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const idlFactory = ({ IDL }: { IDL: any }) => IDL.Service({})
+
+${reactorInstance(vars)}
+
+${actorHooks(vars)}
+
+export { idlFactory }
+export type { ${serviceName} }
+`;
+}
+
+// src/templates/query.ts
+function generateQueryHook(options) {
+  const { canisterName, method, type = "query" } = options;
+  const reactorName = getReactorName(canisterName);
+  const hookExportName = getHookExportName(method.name, type);
+  const isSuspense = type === "suspenseQuery";
+  const creatorFn = isSuspense ? "createSuspenseQuery" : "createQuery";
+  const factoryFn = isSuspense ? "createSuspenseQueryFactory" : "createQueryFactory";
+  const hookName = isSuspense ? "useSuspenseQuery" : "useQuery";
+  if (method.hasArgs) {
+    return `/**
+ * Query Factory: ${method.name}
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * @example
+ * const { data } = ${hookExportName}([arg1, arg2]).${hookName}()
+ * const data = await ${hookExportName}([arg1, arg2]).fetch()
+ * ${hookExportName}([arg1, arg2]).invalidate()
+ */
+
+import { ${factoryFn} } from "@ic-reactor/react"
+import { ${reactorName} } from "../reactor"
+
+export const ${hookExportName} = ${factoryFn}(${reactorName}, {
+  functionName: "${method.name}",
+})
+`;
+  }
+  return `/**
+ * Query: ${method.name}
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * @example
+ * const { data } = ${hookExportName}.${hookName}()
+ * const data = await ${hookExportName}.fetch()
+ * ${hookExportName}.invalidate()
+ */
+
+import { ${creatorFn} } from "@ic-reactor/react"
+import { ${reactorName} } from "../reactor"
+
+export const ${hookExportName} = ${creatorFn}(${reactorName}, {
+  functionName: "${method.name}",
+})
+`;
+}
+
+// src/templates/mutation.ts
+function generateMutationHook(options) {
+  const { canisterName, method } = options;
+  const pascalMethod = toPascalCase(method.name);
+  const reactorName = getReactorName(canisterName);
+  const hookExportName = getHookExportName(method.name, "mutation");
+  return `/**
+ * Mutation: ${method.name}
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * @example
+ * const { mutate, isPending } = ${hookExportName}.useMutation()
+ * mutate(${method.hasArgs ? "[arg1, arg2]" : "[]"})
+ *
+ * // Direct execution (outside React)
+ * const result = await ${hookExportName}.execute(${method.hasArgs ? "[arg1, arg2]" : "[]"})
+ */
+
+import { createMutation } from "@ic-reactor/react"
+import { ${reactorName} } from "../reactor"
+
+export const ${hookExportName} = createMutation(${reactorName}, {
+  functionName: "${method.name}",
+})
+
+/** React hook for ${method.name} */
+export const use${pascalMethod}Mutation = ${hookExportName}.useMutation
+
+/** Execute ${method.name} directly (outside React) */
+export const execute${pascalMethod} = ${hookExportName}.execute
+`;
+}
+
+// src/templates/infiniteQuery.ts
+function generateInfiniteQueryHook(options) {
+  const { canisterName, method, type = "infiniteQuery" } = options;
+  const reactorName = getReactorName(canisterName);
+  const serviceName = getServiceTypeName(canisterName);
+  const hookExportName = getHookExportName(method.name, type);
+  const reactHookName = getReactHookName(method.name, type);
+  return `/**
+ * Infinite Query: ${method.name}
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * \u26A0\uFE0F CUSTOMIZATION REQUIRED: Configure getArgs and getNextPageParam below.
+ *
+ * @example
+ * const { data, fetchNextPage, hasNextPage } = ${hookExportName}.useInfiniteQuery()
+ * const allItems = data?.pages.flatMap(page => page.items) ?? []
+ */
+
+import { createInfiniteQuery } from "@ic-reactor/react"
+import { ${reactorName}, type ${serviceName} } from "../reactor"
+
+/** Define your pagination cursor type */
+type PageCursor = number
+
+export const ${hookExportName} = createInfiniteQuery(${reactorName}, {
+  functionName: "${method.name}",
+
+  initialPageParam: 0 as PageCursor,
+
+  /** Convert page param to method arguments \u2014 customize for your API */
+  getArgs: (pageParam: PageCursor) => {
+    return [{ offset: pageParam, limit: 10 }] as Parameters<${serviceName}["${method.name}"]>
+  },
+
+  /** Extract next page param \u2014 return undefined when no more pages */
+  getNextPageParam: (lastPage, allPages, lastPageParam) => {
+    // Example: offset-based
+    // if (lastPage.items.length < 10) return undefined
+    // return lastPageParam + 10
+    return undefined
+  },
+})
+
+/** React hook for paginated ${method.name} */
+export const ${reactHookName} = ${hookExportName}.useInfiniteQuery
+`;
+}
+export {
+  declarationsExist,
+  extractMethods,
+  formatMethodForDisplay,
+  generateDeclarations,
+  generateInfiniteQueryHook,
+  generateMutationHook,
+  generateQueryHook,
+  generateReactorFile,
+  getHookExportName,
+  getHookFileName,
+  getMethodsByType,
+  getReactHookName,
+  getReactorName,
+  getServiceTypeName,
+  parseDIDFile,
+  saveCandidFile,
+  toCamelCase,
+  toPascalCase
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ic-reactor/codegen",
+  "version": "0.1.0",
+  "description": "Shared code generation utilities for IC Reactor",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --tsconfig tsconfig.json",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch --tsconfig tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "internet-computer",
+    "candid",
+    "ic-reactor",
+    "codegen",
+    "dfinity",
+    "icp"
+  ],
+  "author": "Behrad Deylami",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/B3Pay/ic-reactor.git",
+    "directory": "packages/codegen"
+  },
+  "dependencies": {
+    "change-case": "^5.4.4"
+  },
+  "peerDependencies": {
+    "@icp-sdk/bindgen": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@icp-sdk/bindgen": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@icp-sdk/bindgen": "^0.2.1",
+    "@types/node": "^25.2.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/bindgen.ts

@@ -0,0 +1,113 @@
+/**
+ * Bindgen utilities
+ *
+ * Generates TypeScript declarations from Candid files using @icp-sdk/bindgen.
+ */
+
+import { generate } from "@icp-sdk/bindgen/core"
+import path from "node:path"
+import fs from "node:fs"
+
+export interface BindgenOptions {
+  /** Path to the .did file */
+  didFile: string
+  /** Output directory for generated declarations */
+  outDir: string
+  /** Canister name (used for naming) */
+  canisterName: string
+}
+
+export interface BindgenResult {
+  success: boolean
+  declarationsDir: string
+  error?: string
+}
+
+/**
+ * Generate TypeScript declarations from a Candid file
+ *
+ * This creates:
+ * - declarations/<canisterName>.did.ts - IDL factory and types
+ */
+export async function generateDeclarations(
+  options: BindgenOptions
+): Promise<BindgenResult> {
+  const { didFile, outDir } = options
+
+  // Ensure the .did file exists
+  if (!fs.existsSync(didFile)) {
+    return {
+      success: false,
+      declarationsDir: "",
+      error: `DID file not found: ${didFile}`,
+    }
+  }
+
+  const declarationsDir = path.join(outDir, "declarations")
+
+  try {
+    // Ensure the output directory exists
+    if (!fs.existsSync(outDir)) {
+      fs.mkdirSync(outDir, { recursive: true })
+    }
+
+    // Clean existing declarations before regenerating
+    if (fs.existsSync(declarationsDir)) {
+      fs.rmSync(declarationsDir, { recursive: true, force: true })
+    }
+    fs.mkdirSync(declarationsDir, { recursive: true })
+
+    // Note: bindgen appends "declarations" internally, so we pass the parent directory
+    await generate({
+      didFile,
+      outDir, // Pass the parent directory; bindgen appends "declarations"
+      output: {
+        actor: {
+          disabled: true, // We don't need actor creation, we use Reactor
+        },
+        force: true, // Overwrite existing files
+      },
+    })
+
+    return {
+      success: true,
+      declarationsDir,
+    }
+  } catch (error) {
+    return {
+      success: false,
+      declarationsDir,
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+/**
+ * Check if declarations already exist for a canister
+ */
+export function declarationsExist(
+  outDir: string,
+  canisterName: string
+): boolean {
+  const declarationsDir = path.join(outDir, "declarations")
+  const didTsPath = path.join(declarationsDir, `${canisterName}.did.ts`)
+  return fs.existsSync(didTsPath)
+}
+
+/**
+ * Save a Candid source to a file (for use with fetch command)
+ */
+export function saveCandidFile(
+  candidSource: string,
+  outDir: string,
+  canisterName: string
+): string {
+  const candidDir = path.join(outDir, "candid")
+  if (!fs.existsSync(candidDir)) {
+    fs.mkdirSync(candidDir, { recursive: true })
+  }
+
+  const candidPath = path.join(candidDir, `${canisterName}.did`)
+  fs.writeFileSync(candidPath, candidSource)
+  return candidPath
+}