@ic-reactor/codegen 0.1.0

package/src/templates/reactor.ts

@@ -0,0 +1,290 @@
+/**
+ * Reactor file template generator
+ *
+ * Generates the reactor instance file for a canister.
+ * Supports simple mode (generic hooks) and advanced mode (per-method typed hooks).
+ */
+
+import path from "node:path"
+import type { ReactorGeneratorOptions } from "../types.js"
+import {
+  toPascalCase,
+  toCamelCase,
+  getReactorName,
+  getServiceTypeName,
+} from "../naming.js"
+import { extractMethods } from "../did.js"
+
+/**
+ * Generate the reactor file content
+ */
+export function generateReactorFile(options: ReactorGeneratorOptions): string {
+  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 = path.basename(canisterConfig.didFile)
+  const declarationsPath = `./declarations/${didFileName}`
+
+  const vars: TemplateVars = {
+    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)
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SHARED TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface TemplateVars {
+  canisterName: string
+  pascalName: string
+  reactorName: string
+  serviceName: string
+  reactorType: string
+  clientManagerPath: string
+  declarationsPath: string
+  useDisplayReactor: boolean
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SHARED SECTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+function reactorInstance(vars: TemplateVars): string {
+  const {
+    pascalName,
+    reactorName,
+    serviceName,
+    reactorType,
+    canisterName,
+    useDisplayReactor,
+  } = vars
+  return `/**
+ * ${pascalName} Reactor — ${useDisplayReactor ? "Display" : "Candid"} mode.
+ * ${useDisplayReactor ? "Automatically converts bigint → string, Principal → string, etc." : "Uses raw Candid types."}
+ */
+export const ${reactorName} = new ${reactorType}<${serviceName}>({
+  clientManager,
+  idlFactory,
+  name: "${canisterName}",
+})`
+}
+
+function actorHooks(vars: TemplateVars): string {
+  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,
+}`
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SIMPLE MODE
+// ═══════════════════════════════════════════════════════════════════════════
+
+function generateSimpleReactorFile(vars: TemplateVars): string {
+  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 }
+`
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ADVANCED MODE
+// ═══════════════════════════════════════════════════════════════════════════
+
+function generateAdvancedReactorFile(
+  vars: TemplateVars,
+  didContent: string
+): string {
+  const {
+    pascalName,
+    reactorName,
+    serviceName,
+    reactorType,
+    clientManagerPath,
+    declarationsPath,
+  } = vars
+
+  const methods = extractMethods(didContent)
+
+  // Determine which extra imports we need based on methods
+  const hasQueryWithoutArgs = methods.some(
+    (m) => m.type === "query" && !m.hasArgs
+  )
+  const hasMutationWithoutArgs = methods.some(
+    (m) => m.type === "mutation" && !m.hasArgs
+  )
+
+  const extraImports: string[] = []
+  if (hasQueryWithoutArgs) extraImports.push("createQuery")
+  if (hasMutationWithoutArgs) extraImports.push("createMutation")
+
+  // Generate per-method static hooks (no-args methods only)
+  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 "" // queries with args don't get static instances
+      } else {
+        if (!hasArgs) {
+          return `
+export const ${camelMethod}Mutation = createMutation(${reactorName}, {
+  functionName: "${name}",
+})`
+        }
+        return "" // mutations with args don't get static instances
+      }
+    })
+    .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} }
+`
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FALLBACK (NO DECLARATIONS)
+// ═══════════════════════════════════════════════════════════════════════════
+
+function generateFallbackReactorFile(vars: TemplateVars): string {
+  const {
+    canisterName,
+    pascalName,
+    serviceName,
+    reactorType,
+    clientManagerPath,
+    declarationsPath,
+  } = vars
+
+  return `/**
+ * ${pascalName} Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * ⚠️ 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 — 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} }
+`
+}

package/src/types.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared types for IC Reactor code generation
+ */
+
+/**
+ * Information about a canister method extracted from a .did file
+ */
+export interface MethodInfo {
+  /** Method name as defined in the Candid interface */
+  name: string
+  /** Whether this method is a query or update (mutation) */
+  type: "query" | "mutation"
+  /** Whether the method accepts arguments */
+  hasArgs: boolean
+  /** Human-readable description of the arguments */
+  argsDescription?: string
+  /** Human-readable description of the return type */
+  returnDescription?: string
+}
+
+/**
+ * Configuration for a single canister
+ */
+export interface CanisterConfig {
+  /** Name of the canister (used for variable naming) */
+  name?: string
+  /** Path to the .did file */
+  didFile: string
+  /** Output directory (default: ./src/canisters/<name>) */
+  outDir?: string
+  /** Use DisplayReactor for automatic type transformations (default: true) */
+  useDisplayReactor?: boolean
+  /**
+   * Path to import ClientManager from (relative to generated file).
+   * The file at this path should export: { clientManager: ClientManager }
+   * Default: "../../lib/client"
+   */
+  clientManagerPath?: string
+  /** Custom canister ID (optional, uses environment by default) */
+  canisterId?: string
+}
+
+/**
+ * Hook generation type
+ */
+export type HookType =
+  | "query"
+  | "suspenseQuery"
+  | "infiniteQuery"
+  | "suspenseInfiniteQuery"
+  | "mutation"
+
+/**
+ * Options for generating a hook file
+ */
+export interface GeneratorOptions {
+  canisterName: string
+  methodName: string
+  methodType: "query" | "mutation"
+  hasArgs: boolean
+  outDir: string
+}
+
+/**
+ * Options for reactor file generation
+ */
+export interface ReactorGeneratorOptions {
+  canisterName: string
+  canisterConfig: CanisterConfig
+  /** Global default clientManagerPath */
+  globalClientManagerPath?: string
+  /** Whether declarations have been generated */
+  hasDeclarations?: boolean
+  /** Whether to generate advanced per-method hooks (default: false) */
+  advanced?: boolean
+  /** DID content (required when advanced=true) */
+  didContent?: string
+}