@ic-reactor/codegen 0.1.0

package/src/did.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest"
+import { extractMethods, formatMethodForDisplay } from "./did"
+import type { MethodInfo } from "./types"
+
+describe("DID Utilities", () => {
+  describe("extractMethods", () => {
+    it("extracts query methods", () => {
+      const didContent = `
+      type User = record { name : text; age : nat };
+      type Item = record { name : text; price : nat };
+
+      service : {
+        get_user: (nat) -> (opt User) query;
+        list_items: () -> (vec Item) query;
+      }`
+      const methods = extractMethods(didContent)
+      expect(methods).toHaveLength(2)
+      expect(methods[0]).toMatchObject({
+        name: "get_user",
+        type: "query",
+        hasArgs: true,
+      })
+      expect(methods[1]).toMatchObject({
+        name: "list_items",
+        type: "query",
+        hasArgs: false,
+      })
+    })
+
+    it("extracts mutation (update) methods", () => {
+      const didContent = `service : {
+        create_user: (User) -> (Result);
+        update_item: (nat, Item) -> (Result);
+      }`
+      const methods = extractMethods(didContent)
+      expect(methods).toHaveLength(2)
+      expect(methods[0]).toMatchObject({
+        name: "create_user",
+        type: "mutation",
+        hasArgs: true,
+      })
+      expect(methods[1]).toMatchObject({
+        name: "update_item",
+        type: "mutation",
+        hasArgs: true,
+      })
+    })
+
+    it("handles composite_query as query", () => {
+      const didContent = `service : {
+        search: (text) -> (vec Item) composite_query;
+      }`
+      const methods = extractMethods(didContent)
+      expect(methods[0].type).toBe("query")
+    })
+
+    it("ignores comments", () => {
+      const didContent = `service : {
+        // This is a comment
+        get_data: () -> (text) query;
+        /* create_data: (text) -> (); */
+      }`
+      const methods = extractMethods(didContent)
+      expect(methods).toHaveLength(1)
+      expect(methods[0].name).toBe("get_data")
+    })
+
+    it("extracts argument and return types correctly", () => {
+      const didContent = `service : {
+        weird_method: (record { foo: text; bar: nat }) -> (variant { Ok: null; Err: text }) query;
+      }`
+      const methods = extractMethods(didContent)
+      expect(methods[0].name).toBe("weird_method")
+      expect(methods[0].argsDescription).toContain(
+        "record { foo: text; bar: nat }"
+      )
+      expect(methods[0].returnDescription).toContain(
+        "variant { Ok: null; Err: text }"
+      )
+    })
+  })
+
+  describe("formatMethodForDisplay", () => {
+    it("formats query method with args", () => {
+      const method: MethodInfo = {
+        name: "search",
+        type: "query",
+        hasArgs: true,
+      }
+      expect(formatMethodForDisplay(method)).toBe("search (query, with args)")
+    })
+
+    it("formats update method without args", () => {
+      const method: MethodInfo = {
+        name: "init",
+        type: "mutation",
+        hasArgs: false,
+      }
+      expect(formatMethodForDisplay(method)).toBe("init (update, no args)")
+    })
+  })
+})

package/src/did.ts

@@ -0,0 +1,85 @@
+/**
+ * DID file parser
+ *
+ * Extracts method information from Candid interface definition files.
+ * Based on the CLI's parser implementation (with comment stripping).
+ */
+
+import fs from "node:fs"
+import type { MethodInfo } from "./types.js"
+
+/**
+ * Parse a .did file and extract method information
+ */
+export function parseDIDFile(didFilePath: string): MethodInfo[] {
+  if (!fs.existsSync(didFilePath)) {
+    throw new Error(`DID file not found: ${didFilePath}`)
+  }
+
+  const content = fs.readFileSync(didFilePath, "utf-8")
+  return extractMethods(content)
+}
+
+/**
+ * Extract methods from DID content
+ *
+ * Handles formats like:
+ * - `name : (args) -> (result)`
+ * - `name : (args) -> (result) query`
+ * - `name : (args) -> (result) composite_query`
+ * - `name : func (args) -> (result)`
+ */
+export function extractMethods(didContent: string): MethodInfo[] {
+  const methods: MethodInfo[] = []
+
+  // Remove comments
+  const cleanContent = didContent
+    .replace(/\/\/.*$/gm, "") // Single line comments
+    .replace(/\/\*[\s\S]*?\*\//g, "") // Multi-line comments
+
+  // Match method definitions
+  // Pattern: name : [func] (args) -> (result) [query|composite_query]
+  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]
+
+    // Determine if it's a query or mutation
+    const isQuery =
+      queryAnnotation === "query" || queryAnnotation === "composite_query"
+
+    methods.push({
+      name,
+      type: isQuery ? "query" : "mutation",
+      hasArgs: args.length > 0 && args !== "",
+      argsDescription: args || undefined,
+      returnDescription: returnType || undefined,
+    })
+  }
+
+  return methods
+}
+
+/**
+ * Get methods by type
+ */
+export function getMethodsByType(
+  methods: MethodInfo[],
+  type: "query" | "mutation"
+): MethodInfo[] {
+  return methods.filter((m) => m.type === type)
+}
+
+/**
+ * Format method info for display
+ */
+export function formatMethodForDisplay(method: MethodInfo): string {
+  const typeLabel = method.type === "query" ? "query" : "update"
+  const argsLabel = method.hasArgs ? "with args" : "no args"
+  return `${method.name} (${typeLabel}, ${argsLabel})`
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @ic-reactor/codegen
+ *
+ * Shared code generation utilities for IC Reactor.
+ * Used by both @ic-reactor/vite-plugin and @ic-reactor/cli.
+ */
+
+// Types
+export type {
+  MethodInfo,
+  CanisterConfig,
+  HookType,
+  GeneratorOptions,
+  ReactorGeneratorOptions,
+} from "./types.js"
+
+// Naming utilities
+export {
+  toPascalCase,
+  toCamelCase,
+  getHookFileName,
+  getHookExportName,
+  getReactHookName,
+  getReactorName,
+  getServiceTypeName,
+} from "./naming.js"
+
+// DID parsing
+export {
+  parseDIDFile,
+  extractMethods,
+  getMethodsByType,
+  formatMethodForDisplay,
+} from "./did.js"
+
+// Bindgen utilities
+export {
+  generateDeclarations,
+  declarationsExist,
+  saveCandidFile,
+} from "./bindgen.js"
+export type { BindgenOptions, BindgenResult } from "./bindgen.js"
+
+// Template generators
+export { generateReactorFile } from "./templates/reactor.js"
+export { generateQueryHook } from "./templates/query.js"
+export type { QueryHookOptions } from "./templates/query.js"
+export { generateMutationHook } from "./templates/mutation.js"
+export type { MutationHookOptions } from "./templates/mutation.js"
+export { generateInfiniteQueryHook } from "./templates/infiniteQuery.js"
+export type { InfiniteQueryHookOptions } from "./templates/infiniteQuery.js"

package/src/naming.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest"
+import {
+  toPascalCase,
+  toCamelCase,
+  getHookFileName,
+  getHookExportName,
+  getReactHookName,
+  getReactorName,
+  getServiceTypeName,
+} from "./naming"
+
+describe("Naming Utilities", () => {
+  describe("Base Conversions", () => {
+    it("converts to PascalCase", () => {
+      expect(toPascalCase("get_user")).toBe("GetUser")
+      expect(toPascalCase("my-canister")).toBe("MyCanister")
+      expect(toPascalCase("list_items_v2")).toBe("ListItemsV2")
+    })
+
+    it("converts to camelCase", () => {
+      expect(toCamelCase("get_user")).toBe("getUser")
+      expect(toCamelCase("my-canister")).toBe("myCanister")
+      expect(toCamelCase("ListItems")).toBe("listItems")
+    })
+  })
+
+  describe("Domain-Specific Naming", () => {
+    it("generates hook file names", () => {
+      expect(getHookFileName("get_user", "query")).toBe("getUserQuery.ts")
+      expect(getHookFileName("update_item", "mutation")).toBe(
+        "updateItemMutation.ts"
+      )
+    })
+
+    it("generates hook export names", () => {
+      expect(getHookExportName("get_user", "query")).toBe("getUserQuery")
+      expect(getHookExportName("update_item", "mutation")).toBe(
+        "updateItemMutation"
+      )
+    })
+
+    it("generates React hook names", () => {
+      expect(getReactHookName("get_user", "query")).toBe("useGetUserQuery")
+      expect(getReactHookName("update_item", "mutation")).toBe(
+        "useUpdateItemMutation"
+      )
+    })
+
+    it("generates reactor names", () => {
+      expect(getReactorName("backend")).toBe("backendReactor")
+      expect(getReactorName("my-canister")).toBe("myCanisterReactor")
+    })
+
+    it("generates service type names", () => {
+      expect(getServiceTypeName("backend")).toBe("BackendService")
+      expect(getServiceTypeName("my-canister")).toBe("MyCanisterService")
+    })
+  })
+})

package/src/naming.ts

@@ -0,0 +1,83 @@
+/**
+ * Naming utilities for code generation
+ *
+ * Uses the `change-case` library for base transformations,
+ * with domain-specific helpers for IC Reactor patterns.
+ */
+
+import { camelCase, pascalCase } from "change-case"
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BASE CASE CONVERSIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert string to PascalCase
+ * @example toPascalCase("get_message") → "GetMessage"
+ * @example toPascalCase("my-canister") → "MyCanister"
+ */
+export function toPascalCase(str: string): string {
+  return pascalCase(str)
+}
+
+/**
+ * Convert string to camelCase
+ * @example toCamelCase("get_message") → "getMessage"
+ * @example toCamelCase("my-canister") → "myCanister"
+ */
+export function toCamelCase(str: string): string {
+  return camelCase(str)
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DOMAIN-SPECIFIC NAMING
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate hook file name
+ * @example getHookFileName("get_message", "query") → "getMessageQuery.ts"
+ */
+export function getHookFileName(methodName: string, hookType: string): string {
+  const camelMethod = toCamelCase(methodName)
+  const pascalType = toPascalCase(hookType)
+  return `${camelMethod}${pascalType}.ts`
+}
+
+/**
+ * Generate hook export name
+ * @example getHookExportName("get_message", "query") → "getMessageQuery"
+ */
+export function getHookExportName(
+  methodName: string,
+  hookType: string
+): string {
+  const camelMethod = toCamelCase(methodName)
+  const pascalType = toPascalCase(hookType)
+  return `${camelMethod}${pascalType}`
+}
+
+/**
+ * Generate React hook name (with use prefix)
+ * @example getReactHookName("get_message", "query") → "useGetMessageQuery"
+ */
+export function getReactHookName(methodName: string, hookType: string): string {
+  const pascalMethod = toPascalCase(methodName)
+  const pascalType = toPascalCase(hookType)
+  return `use${pascalMethod}${pascalType}`
+}
+
+/**
+ * Generate reactor variable name
+ * @example getReactorName("backend") → "backendReactor"
+ */
+export function getReactorName(canisterName: string): string {
+  return `${toCamelCase(canisterName)}Reactor`
+}
+
+/**
+ * Generate service type name
+ * @example getServiceTypeName("backend") → "BackendService"
+ */
+export function getServiceTypeName(canisterName: string): string {
+  return `${toPascalCase(canisterName)}Service`
+}

package/src/templates/__snapshots__/infiniteQuery.test.ts.snap

@@ -0,0 +1,44 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Infinite Query Hook Generation > generates infinite query hook correctly 1`] = `
+"/**
+ * Infinite Query: list_items
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * ⚠️ CUSTOMIZATION REQUIRED: Configure getArgs and getNextPageParam below.
+ *
+ * @example
+ * const { data, fetchNextPage, hasNextPage } = listItemsInfiniteQuery.useInfiniteQuery()
+ * const allItems = data?.pages.flatMap(page => page.items) ?? []
+ */
+
+import { createInfiniteQuery } from "@ic-reactor/react"
+import { myCanisterReactor, type MyCanisterService } from "../reactor"
+
+/** Define your pagination cursor type */
+type PageCursor = number
+
+export const listItemsInfiniteQuery = createInfiniteQuery(myCanisterReactor, {
+  functionName: "list_items",
+
+  initialPageParam: 0 as PageCursor,
+
+  /** Convert page param to method arguments — customize for your API */
+  getArgs: (pageParam: PageCursor) => {
+    return [{ offset: pageParam, limit: 10 }] as Parameters<MyCanisterService["list_items"]>
+  },
+
+  /** Extract next page param — 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 list_items */
+export const useListItemsInfiniteQuery = listItemsInfiniteQuery.useInfiniteQuery
+"
+`;

package/src/templates/__snapshots__/mutation.test.ts.snap

@@ -0,0 +1,59 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Mutation Hook Generation > generates hook correctly for mutation with args 1`] = `
+"/**
+ * Mutation: create_item
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * @example
+ * const { mutate, isPending } = createItemMutation.useMutation()
+ * mutate([arg1, arg2])
+ *
+ * // Direct execution (outside React)
+ * const result = await createItemMutation.execute([arg1, arg2])
+ */
+
+import { createMutation } from "@ic-reactor/react"
+import { myCanisterReactor } from "../reactor"
+
+export const createItemMutation = createMutation(myCanisterReactor, {
+  functionName: "create_item",
+})
+
+/** React hook for create_item */
+export const useCreateItemMutation = createItemMutation.useMutation
+
+/** Execute create_item directly (outside React) */
+export const executeCreateItem = createItemMutation.execute
+"
+`;
+
+exports[`Mutation Hook Generation > generates hook correctly for mutation without args 1`] = `
+"/**
+ * Mutation: init_system
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * @example
+ * const { mutate, isPending } = initSystemMutation.useMutation()
+ * mutate([])
+ *
+ * // Direct execution (outside React)
+ * const result = await initSystemMutation.execute([])
+ */
+
+import { createMutation } from "@ic-reactor/react"
+import { myCanisterReactor } from "../reactor"
+
+export const initSystemMutation = createMutation(myCanisterReactor, {
+  functionName: "init_system",
+})
+
+/** React hook for init_system */
+export const useInitSystemMutation = initSystemMutation.useMutation
+
+/** Execute init_system directly (outside React) */
+export const executeInitSystem = initSystemMutation.execute
+"
+`;

package/src/templates/__snapshots__/query.test.ts.snap

@@ -0,0 +1,64 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Query Hook Generation > generates hook for query with arguments (factory) 1`] = `
+"/**
+ * Query Factory: get_user
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * @example
+ * const { data } = getUserQuery([arg1, arg2]).useQuery()
+ * const data = await getUserQuery([arg1, arg2]).fetch()
+ * getUserQuery([arg1, arg2]).invalidate()
+ */
+
+import { createQueryFactory } from "@ic-reactor/react"
+import { myCanisterReactor } from "../reactor"
+
+export const getUserQuery = createQueryFactory(myCanisterReactor, {
+  functionName: "get_user",
+})
+"
+`;
+
+exports[`Query Hook Generation > generates hook for query without arguments (static) 1`] = `
+"/**
+ * Query: list_items
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * @example
+ * const { data } = listItemsQuery.useQuery()
+ * const data = await listItemsQuery.fetch()
+ * listItemsQuery.invalidate()
+ */
+
+import { createQuery } from "@ic-reactor/react"
+import { myCanisterReactor } from "../reactor"
+
+export const listItemsQuery = createQuery(myCanisterReactor, {
+  functionName: "list_items",
+})
+"
+`;
+
+exports[`Query Hook Generation > generates suspense hooks correctly 1`] = `
+"/**
+ * Query Factory: get_user
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * @example
+ * const { data } = getUserSuspenseQuery([arg1, arg2]).useSuspenseQuery()
+ * const data = await getUserSuspenseQuery([arg1, arg2]).fetch()
+ * getUserSuspenseQuery([arg1, arg2]).invalidate()
+ */
+
+import { createSuspenseQueryFactory } from "@ic-reactor/react"
+import { myCanisterReactor } from "../reactor"
+
+export const getUserSuspenseQuery = createSuspenseQueryFactory(myCanisterReactor, {
+  functionName: "get_user",
+})
+"
+`;