@ic-reactor/codegen 0.1.0

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

@@ -0,0 +1,163 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Reactor File Generation > Advanced Mode > generates per-method hooks correctly 1`] = `
+"/**
+ * MyCanister Reactor (Advanced)
+ *
+ * Auto-generated by @ic-reactor/codegen
+ * Includes reactor instance, actor hooks, and per-method static hooks.
+ */
+
+import {
+  DisplayReactor,
+  createActorHooks,
+  createQuery,
+  createMutation,
+} from "@ic-reactor/react"
+import { clientManager } from "../../client"
+import { idlFactory, type _SERVICE } from "./declarations/my_canister.did"
+
+type MyCanisterService = _SERVICE
+
+/**
+ * MyCanister Reactor — Display mode.
+ * Automatically converts bigint → string, Principal → string, etc.
+ */
+export const myCanisterReactor = new DisplayReactor<MyCanisterService>({
+  clientManager,
+  idlFactory,
+  name: "my_canister",
+})
+
+const {
+  useActorQuery: useMyCanisterQuery,
+  useActorSuspenseQuery: useMyCanisterSuspenseQuery,
+  useActorInfiniteQuery: useMyCanisterInfiniteQuery,
+  useActorSuspenseInfiniteQuery: useMyCanisterSuspenseInfiniteQuery,
+  useActorMutation: useMyCanisterMutation,
+  useActorMethod: useMyCanisterMethod,
+} = createActorHooks(myCanisterReactor)
+
+export {
+  useMyCanisterQuery,
+  useMyCanisterSuspenseQuery,
+  useMyCanisterInfiniteQuery,
+  useMyCanisterSuspenseInfiniteQuery,
+  useMyCanisterMutation,
+  useMyCanisterMethod,
+}
+
+// Per-method static hooks (no-args methods only)
+
+export const listItemsQuery = createQuery(myCanisterReactor, {
+  functionName: "list_items",
+})
+
+export const updateStatusMutation = createMutation(myCanisterReactor, {
+  functionName: "update_status",
+})
+
+export { idlFactory }
+export type { MyCanisterService }
+"
+`;
+
+exports[`Reactor File Generation > Fallback Mode > generates correctly without declarations 1`] = `
+"/**
+ * MyCanister Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen
+ *
+ * ⚠️ Declarations were not generated. Run:
+ *   npx @icp-sdk/bindgen --input <path-to-did> --output ./my_canister/declarations
+ * Then uncomment the import below and remove the fallback type.
+ */
+
+import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+import { clientManager } from "../../client"
+
+// TODO: Uncomment after generating declarations:
+// import { idlFactory, type _SERVICE as MyCanisterService } from "./declarations/my_canister.did"
+
+// Fallback — replace with generated types
+type MyCanisterService = Record<string, (...args: unknown[]) => Promise<unknown>>
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const idlFactory = ({ IDL }: { IDL: any }) => IDL.Service({})
+
+/**
+ * MyCanister Reactor — Display mode.
+ * Automatically converts bigint → string, Principal → string, etc.
+ */
+export const myCanisterReactor = new DisplayReactor<MyCanisterService>({
+  clientManager,
+  idlFactory,
+  name: "my_canister",
+})
+
+const {
+  useActorQuery: useMyCanisterQuery,
+  useActorSuspenseQuery: useMyCanisterSuspenseQuery,
+  useActorInfiniteQuery: useMyCanisterInfiniteQuery,
+  useActorSuspenseInfiniteQuery: useMyCanisterSuspenseInfiniteQuery,
+  useActorMutation: useMyCanisterMutation,
+  useActorMethod: useMyCanisterMethod,
+} = createActorHooks(myCanisterReactor)
+
+export {
+  useMyCanisterQuery,
+  useMyCanisterSuspenseQuery,
+  useMyCanisterInfiniteQuery,
+  useMyCanisterSuspenseInfiniteQuery,
+  useMyCanisterMutation,
+  useMyCanisterMethod,
+}
+
+export { idlFactory }
+export type { MyCanisterService }
+"
+`;
+
+exports[`Reactor File Generation > Simple Mode > generates correctly 1`] = `
+"/**
+ * MyCanister Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen
+ */
+
+import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+import { clientManager } from "../../client"
+import { idlFactory, type _SERVICE } from "./declarations/my_canister.did"
+
+export type MyCanisterService = _SERVICE
+
+/**
+ * MyCanister Reactor — Display mode.
+ * Automatically converts bigint → string, Principal → string, etc.
+ */
+export const myCanisterReactor = new DisplayReactor<MyCanisterService>({
+  clientManager,
+  idlFactory,
+  name: "my_canister",
+})
+
+const {
+  useActorQuery: useMyCanisterQuery,
+  useActorSuspenseQuery: useMyCanisterSuspenseQuery,
+  useActorInfiniteQuery: useMyCanisterInfiniteQuery,
+  useActorSuspenseInfiniteQuery: useMyCanisterSuspenseInfiniteQuery,
+  useActorMutation: useMyCanisterMutation,
+  useActorMethod: useMyCanisterMethod,
+} = createActorHooks(myCanisterReactor)
+
+export {
+  useMyCanisterQuery,
+  useMyCanisterSuspenseQuery,
+  useMyCanisterInfiniteQuery,
+  useMyCanisterSuspenseInfiniteQuery,
+  useMyCanisterMutation,
+  useMyCanisterMethod,
+}
+
+export { idlFactory }
+"
+`;

package/src/templates/infiniteQuery.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest"
+import {
+  generateInfiniteQueryHook,
+  InfiniteQueryHookOptions,
+} from "./infiniteQuery"
+import type { MethodInfo } from "../types"
+
+describe("Infinite Query Hook Generation", () => {
+  const listItems: MethodInfo = {
+    name: "list_items",
+    type: "query",
+    hasArgs: true,
+  }
+
+  it("generates infinite query hook correctly", () => {
+    const options: InfiniteQueryHookOptions = {
+      canisterName: "my_canister",
+      method: listItems,
+      type: "infiniteQuery",
+    }
+    const result = generateInfiniteQueryHook(options)
+    expect(result).toMatchSnapshot()
+    expect(result).toContain("createInfiniteQuery(myCanisterReactor, {")
+    expect(result).toContain(
+      "export const useListItemsInfiniteQuery = listItemsInfiniteQuery.useInfiniteQuery"
+    )
+    // Should contain default pagination logic placeholders
+    expect(result).toContain("initialPageParam: 0 as PageCursor")
+  })
+
+  it("handles suspense infinite query type", () => {
+    const options: InfiniteQueryHookOptions = {
+      canisterName: "my_canister",
+      method: listItems,
+      type: "suspenseInfiniteQuery",
+    }
+    const result = generateInfiniteQueryHook(options)
+    expect(result).toContain(
+      "export const useListItemsSuspenseInfiniteQuery = listItemsSuspenseInfiniteQuery.useInfiniteQuery"
+    )
+  })
+})

package/src/templates/infiniteQuery.ts

@@ -0,0 +1,74 @@
+/**
+ * Infinite Query hook template generator
+ *
+ * Generates createInfiniteQuery-based hooks for paginated canister methods.
+ */
+
+import type { MethodInfo, HookType } from "../types.js"
+import {
+  getReactorName,
+  getServiceTypeName,
+  getHookExportName,
+  getReactHookName,
+} from "../naming.js"
+
+export interface InfiniteQueryHookOptions {
+  canisterName: string
+  method: MethodInfo
+  type?: HookType
+}
+
+/**
+ * Generate an infinite query hook file content
+ */
+export function generateInfiniteQueryHook(
+  options: InfiniteQueryHookOptions
+): string {
+  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
+ *
+ * ⚠️ 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 — customize for your API */
+  getArgs: (pageParam: PageCursor) => {
+    return [{ offset: pageParam, limit: 10 }] as Parameters<${serviceName}["${method.name}"]>
+  },
+
+  /** 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 ${method.name} */
+export const ${reactHookName} = ${hookExportName}.useInfiniteQuery
+`
+}

package/src/templates/mutation.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest"
+import { generateMutationHook, MutationHookOptions } from "./mutation"
+import type { MethodInfo } from "../types"
+
+describe("Mutation Hook Generation", () => {
+  const methodWithArgs: MethodInfo = {
+    name: "create_item",
+    type: "mutation",
+    hasArgs: true,
+  }
+
+  const methodNoArgs: MethodInfo = {
+    name: "init_system",
+    type: "mutation",
+    hasArgs: false,
+  }
+
+  it("generates hook correctly for mutation with args", () => {
+    const options: MutationHookOptions = {
+      canisterName: "my_canister",
+      method: methodWithArgs,
+    }
+    const result = generateMutationHook(options)
+    expect(result).toMatchSnapshot()
+    expect(result).toContain("createMutation(myCanisterReactor, {")
+    expect(result).toContain(
+      "export const useCreateItemMutation = createItemMutation.useMutation"
+    )
+  })
+
+  it("generates hook correctly for mutation without args", () => {
+    const options: MutationHookOptions = {
+      canisterName: "my_canister",
+      method: methodNoArgs,
+    }
+    const result = generateMutationHook(options)
+    expect(result).toMatchSnapshot()
+    expect(result).toContain("createMutation(myCanisterReactor, {")
+    expect(result).toContain(
+      "export const executeInitSystem = initSystemMutation.execute"
+    )
+  })
+})

package/src/templates/mutation.ts

@@ -0,0 +1,51 @@
+/**
+ * Mutation hook template generator
+ *
+ * Generates createMutation-based hooks for canister update methods.
+ */
+
+import type { MethodInfo } from "../types.js"
+import { toPascalCase, getHookExportName, getReactorName } from "../naming.js"
+
+export interface MutationHookOptions {
+  canisterName: string
+  method: MethodInfo
+}
+
+/**
+ * Generate a mutation hook file content
+ */
+export function generateMutationHook(options: MutationHookOptions): string {
+  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
+`
+}

package/src/templates/query.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest"
+import { generateQueryHook, QueryHookOptions } from "./query"
+import type { MethodInfo } from "../types"
+
+describe("Query Hook Generation", () => {
+  const methodWithArgs: MethodInfo = {
+    name: "get_user",
+    type: "query",
+    hasArgs: true,
+  }
+
+  const methodNoArgs: MethodInfo = {
+    name: "list_items",
+    type: "query",
+    hasArgs: false,
+  }
+
+  it("generates hook for query with arguments (factory)", () => {
+    const options: QueryHookOptions = {
+      canisterName: "my_canister",
+      method: methodWithArgs,
+    }
+    expect(generateQueryHook(options)).toMatchSnapshot()
+  })
+
+  it("generates hook for query without arguments (static)", () => {
+    const options: QueryHookOptions = {
+      canisterName: "my_canister",
+      method: methodNoArgs,
+    }
+    expect(generateQueryHook(options)).toMatchSnapshot()
+  })
+
+  it("generates suspense hooks correctly", () => {
+    const options: QueryHookOptions = {
+      canisterName: "my_canister",
+      method: methodWithArgs,
+      type: "suspenseQuery",
+    }
+    const result = generateQueryHook(options)
+    expect(result).toMatchSnapshot()
+    expect(result).toContain("createSuspenseQueryFactory")
+  })
+})

package/src/templates/query.ts

@@ -0,0 +1,71 @@
+/**
+ * Query hook template generator
+ *
+ * Generates createQuery/createQueryFactory-based hooks for canister query methods.
+ */
+
+import type { MethodInfo, HookType } from "../types.js"
+import { getHookExportName, getReactorName } from "../naming.js"
+
+export interface QueryHookOptions {
+  canisterName: string
+  method: MethodInfo
+  type?: HookType
+}
+
+/**
+ * Generate a query hook file content
+ */
+export function generateQueryHook(options: QueryHookOptions): string {
+  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}",
+})
+`
+}

package/src/templates/reactor.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest"
+import { generateReactorFile } from "./reactor"
+import type { ReactorGeneratorOptions } from "../types"
+
+describe("Reactor File Generation", () => {
+  const baseOptions: ReactorGeneratorOptions = {
+    canisterName: "my_canister",
+    canisterConfig: {
+      didFile: "path/to/my_canister.did",
+      outDir: "src/declarations/my_canister",
+      clientManagerPath: "../../client",
+    },
+    hasDeclarations: true,
+  }
+
+  describe("Simple Mode", () => {
+    it("generates correctly", () => {
+      const result = generateReactorFile(baseOptions)
+      expect(result).toMatchSnapshot()
+    })
+
+    it("uses default client path if not provided", () => {
+      const options = { ...baseOptions, canisterConfig: { didFile: "foo.did" } }
+      const result = generateReactorFile(options)
+      expect(result).toContain(
+        'import { clientManager } from "../../lib/client"'
+      )
+    })
+  })
+
+  describe("Advanced Mode", () => {
+    it("generates per-method hooks correctly", () => {
+      const didContent = `service : {
+        get_user: (nat) -> (opt User) query;
+        list_items: () -> (vec Item) query;
+        create_item: (Item) -> (Result);
+        update_status: () -> (Result); // No args mutation
+      }`
+
+      const options: ReactorGeneratorOptions = {
+        ...baseOptions,
+        advanced: true,
+        didContent,
+      }
+
+      const result = generateReactorFile(options)
+      expect(result).toMatchSnapshot()
+      // Should include static query creation for no-arg method
+      expect(result).toContain(
+        "export const listItemsQuery = createQuery(myCanisterReactor, {"
+      )
+      // Should handle mutation
+      expect(result).toContain(
+        "export const updateStatusMutation = createMutation(myCanisterReactor, {"
+      )
+      // Should NOT handle methods with args
+      expect(result).not.toContain("export const getUserQuery = createQuery")
+      expect(result).not.toContain(
+        "export const createItemMutation = createMutation"
+      )
+    })
+  })
+
+  describe("Fallback Mode", () => {
+    it("generates correctly without declarations", () => {
+      const options: ReactorGeneratorOptions = {
+        ...baseOptions,
+        hasDeclarations: false,
+      }
+      const result = generateReactorFile(options)
+      expect(result).toMatchSnapshot()
+
+      expect(result).toContain(
+        "type MyCanisterService = Record<string, (...args: unknown[]) => Promise<unknown>>"
+      )
+    })
+  })
+})