@ic-reactor/codegen 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,237 @@
+/**
+ * Shared types for IC Reactor code generation
+ */
+/**
+ * Information about a canister method extracted from a .did file
+ */
+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
+ */
+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
+ */
+type HookType = "query" | "suspenseQuery" | "infiniteQuery" | "suspenseInfiniteQuery" | "mutation";
+/**
+ * Options for generating a hook file
+ */
+interface GeneratorOptions {
+    canisterName: string;
+    methodName: string;
+    methodType: "query" | "mutation";
+    hasArgs: boolean;
+    outDir: string;
+}
+/**
+ * Options for reactor file generation
+ */
+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;
+}
+
+/**
+ * Naming utilities for code generation
+ *
+ * Uses the `change-case` library for base transformations,
+ * with domain-specific helpers for IC Reactor patterns.
+ */
+/**
+ * Convert string to PascalCase
+ * @example toPascalCase("get_message") → "GetMessage"
+ * @example toPascalCase("my-canister") → "MyCanister"
+ */
+declare function toPascalCase(str: string): string;
+/**
+ * Convert string to camelCase
+ * @example toCamelCase("get_message") → "getMessage"
+ * @example toCamelCase("my-canister") → "myCanister"
+ */
+declare function toCamelCase(str: string): string;
+/**
+ * Generate hook file name
+ * @example getHookFileName("get_message", "query") → "getMessageQuery.ts"
+ */
+declare function getHookFileName(methodName: string, hookType: string): string;
+/**
+ * Generate hook export name
+ * @example getHookExportName("get_message", "query") → "getMessageQuery"
+ */
+declare function getHookExportName(methodName: string, hookType: string): string;
+/**
+ * Generate React hook name (with use prefix)
+ * @example getReactHookName("get_message", "query") → "useGetMessageQuery"
+ */
+declare function getReactHookName(methodName: string, hookType: string): string;
+/**
+ * Generate reactor variable name
+ * @example getReactorName("backend") → "backendReactor"
+ */
+declare function getReactorName(canisterName: string): string;
+/**
+ * Generate service type name
+ * @example getServiceTypeName("backend") → "BackendService"
+ */
+declare function getServiceTypeName(canisterName: string): string;
+
+/**
+ * DID file parser
+ *
+ * Extracts method information from Candid interface definition files.
+ * Based on the CLI's parser implementation (with comment stripping).
+ */
+
+/**
+ * Parse a .did file and extract method information
+ */
+declare function parseDIDFile(didFilePath: string): MethodInfo[];
+/**
+ * Extract methods from DID content
+ *
+ * Handles formats like:
+ * - `name : (args) -> (result)`
+ * - `name : (args) -> (result) query`
+ * - `name : (args) -> (result) composite_query`
+ * - `name : func (args) -> (result)`
+ */
+declare function extractMethods(didContent: string): MethodInfo[];
+/**
+ * Get methods by type
+ */
+declare function getMethodsByType(methods: MethodInfo[], type: "query" | "mutation"): MethodInfo[];
+/**
+ * Format method info for display
+ */
+declare function formatMethodForDisplay(method: MethodInfo): string;
+
+/**
+ * Bindgen utilities
+ *
+ * Generates TypeScript declarations from Candid files using @icp-sdk/bindgen.
+ */
+interface BindgenOptions {
+    /** Path to the .did file */
+    didFile: string;
+    /** Output directory for generated declarations */
+    outDir: string;
+    /** Canister name (used for naming) */
+    canisterName: string;
+}
+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
+ */
+declare function generateDeclarations(options: BindgenOptions): Promise<BindgenResult>;
+/**
+ * Check if declarations already exist for a canister
+ */
+declare function declarationsExist(outDir: string, canisterName: string): boolean;
+/**
+ * Save a Candid source to a file (for use with fetch command)
+ */
+declare function saveCandidFile(candidSource: string, outDir: string, canisterName: string): string;
+
+/**
+ * Reactor file template generator
+ *
+ * Generates the reactor instance file for a canister.
+ * Supports simple mode (generic hooks) and advanced mode (per-method typed hooks).
+ */
+
+/**
+ * Generate the reactor file content
+ */
+declare function generateReactorFile(options: ReactorGeneratorOptions): string;
+
+/**
+ * Query hook template generator
+ *
+ * Generates createQuery/createQueryFactory-based hooks for canister query methods.
+ */
+
+interface QueryHookOptions {
+    canisterName: string;
+    method: MethodInfo;
+    type?: HookType;
+}
+/**
+ * Generate a query hook file content
+ */
+declare function generateQueryHook(options: QueryHookOptions): string;
+
+/**
+ * Mutation hook template generator
+ *
+ * Generates createMutation-based hooks for canister update methods.
+ */
+
+interface MutationHookOptions {
+    canisterName: string;
+    method: MethodInfo;
+}
+/**
+ * Generate a mutation hook file content
+ */
+declare function generateMutationHook(options: MutationHookOptions): string;
+
+/**
+ * Infinite Query hook template generator
+ *
+ * Generates createInfiniteQuery-based hooks for paginated canister methods.
+ */
+
+interface InfiniteQueryHookOptions {
+    canisterName: string;
+    method: MethodInfo;
+    type?: HookType;
+}
+/**
+ * Generate an infinite query hook file content
+ */
+declare function generateInfiniteQueryHook(options: InfiniteQueryHookOptions): string;
+
+export { type BindgenOptions, type BindgenResult, type CanisterConfig, type GeneratorOptions, type HookType, type InfiniteQueryHookOptions, type MethodInfo, type MutationHookOptions, type QueryHookOptions, type ReactorGeneratorOptions, declarationsExist, extractMethods, formatMethodForDisplay, generateDeclarations, generateInfiniteQueryHook, generateMutationHook, generateQueryHook, generateReactorFile, getHookExportName, getHookFileName, getMethodsByType, getReactHookName, getReactorName, getServiceTypeName, parseDIDFile, saveCandidFile, toCamelCase, toPascalCase };

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Shared types for IC Reactor code generation
+ */
+/**
+ * Information about a canister method extracted from a .did file
+ */
+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
+ */
+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
+ */
+type HookType = "query" | "suspenseQuery" | "infiniteQuery" | "suspenseInfiniteQuery" | "mutation";
+/**
+ * Options for generating a hook file
+ */
+interface GeneratorOptions {
+    canisterName: string;
+    methodName: string;
+    methodType: "query" | "mutation";
+    hasArgs: boolean;
+    outDir: string;
+}
+/**
+ * Options for reactor file generation
+ */
+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;
+}
+
+/**
+ * Naming utilities for code generation
+ *
+ * Uses the `change-case` library for base transformations,
+ * with domain-specific helpers for IC Reactor patterns.
+ */
+/**
+ * Convert string to PascalCase
+ * @example toPascalCase("get_message") → "GetMessage"
+ * @example toPascalCase("my-canister") → "MyCanister"
+ */
+declare function toPascalCase(str: string): string;
+/**
+ * Convert string to camelCase
+ * @example toCamelCase("get_message") → "getMessage"
+ * @example toCamelCase("my-canister") → "myCanister"
+ */
+declare function toCamelCase(str: string): string;
+/**
+ * Generate hook file name
+ * @example getHookFileName("get_message", "query") → "getMessageQuery.ts"
+ */
+declare function getHookFileName(methodName: string, hookType: string): string;
+/**
+ * Generate hook export name
+ * @example getHookExportName("get_message", "query") → "getMessageQuery"
+ */
+declare function getHookExportName(methodName: string, hookType: string): string;
+/**
+ * Generate React hook name (with use prefix)
+ * @example getReactHookName("get_message", "query") → "useGetMessageQuery"
+ */
+declare function getReactHookName(methodName: string, hookType: string): string;
+/**
+ * Generate reactor variable name
+ * @example getReactorName("backend") → "backendReactor"
+ */
+declare function getReactorName(canisterName: string): string;
+/**
+ * Generate service type name
+ * @example getServiceTypeName("backend") → "BackendService"
+ */
+declare function getServiceTypeName(canisterName: string): string;
+
+/**
+ * DID file parser
+ *
+ * Extracts method information from Candid interface definition files.
+ * Based on the CLI's parser implementation (with comment stripping).
+ */
+
+/**
+ * Parse a .did file and extract method information
+ */
+declare function parseDIDFile(didFilePath: string): MethodInfo[];
+/**
+ * Extract methods from DID content
+ *
+ * Handles formats like:
+ * - `name : (args) -> (result)`
+ * - `name : (args) -> (result) query`
+ * - `name : (args) -> (result) composite_query`
+ * - `name : func (args) -> (result)`
+ */
+declare function extractMethods(didContent: string): MethodInfo[];
+/**
+ * Get methods by type
+ */
+declare function getMethodsByType(methods: MethodInfo[], type: "query" | "mutation"): MethodInfo[];
+/**
+ * Format method info for display
+ */
+declare function formatMethodForDisplay(method: MethodInfo): string;
+
+/**
+ * Bindgen utilities
+ *
+ * Generates TypeScript declarations from Candid files using @icp-sdk/bindgen.
+ */
+interface BindgenOptions {
+    /** Path to the .did file */
+    didFile: string;
+    /** Output directory for generated declarations */
+    outDir: string;
+    /** Canister name (used for naming) */
+    canisterName: string;
+}
+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
+ */
+declare function generateDeclarations(options: BindgenOptions): Promise<BindgenResult>;
+/**
+ * Check if declarations already exist for a canister
+ */
+declare function declarationsExist(outDir: string, canisterName: string): boolean;
+/**
+ * Save a Candid source to a file (for use with fetch command)
+ */
+declare function saveCandidFile(candidSource: string, outDir: string, canisterName: string): string;
+
+/**
+ * Reactor file template generator
+ *
+ * Generates the reactor instance file for a canister.
+ * Supports simple mode (generic hooks) and advanced mode (per-method typed hooks).
+ */
+
+/**
+ * Generate the reactor file content
+ */
+declare function generateReactorFile(options: ReactorGeneratorOptions): string;
+
+/**
+ * Query hook template generator
+ *
+ * Generates createQuery/createQueryFactory-based hooks for canister query methods.
+ */
+
+interface QueryHookOptions {
+    canisterName: string;
+    method: MethodInfo;
+    type?: HookType;
+}
+/**
+ * Generate a query hook file content
+ */
+declare function generateQueryHook(options: QueryHookOptions): string;
+
+/**
+ * Mutation hook template generator
+ *
+ * Generates createMutation-based hooks for canister update methods.
+ */
+
+interface MutationHookOptions {
+    canisterName: string;
+    method: MethodInfo;
+}
+/**
+ * Generate a mutation hook file content
+ */
+declare function generateMutationHook(options: MutationHookOptions): string;
+
+/**
+ * Infinite Query hook template generator
+ *
+ * Generates createInfiniteQuery-based hooks for paginated canister methods.
+ */
+
+interface InfiniteQueryHookOptions {
+    canisterName: string;
+    method: MethodInfo;
+    type?: HookType;
+}
+/**
+ * Generate an infinite query hook file content
+ */
+declare function generateInfiniteQueryHook(options: InfiniteQueryHookOptions): string;
+
+export { type BindgenOptions, type BindgenResult, type CanisterConfig, type GeneratorOptions, type HookType, type InfiniteQueryHookOptions, type MethodInfo, type MutationHookOptions, type QueryHookOptions, type ReactorGeneratorOptions, declarationsExist, extractMethods, formatMethodForDisplay, generateDeclarations, generateInfiniteQueryHook, generateMutationHook, generateQueryHook, generateReactorFile, getHookExportName, getHookFileName, getMethodsByType, getReactHookName, getReactorName, getServiceTypeName, parseDIDFile, saveCandidFile, toCamelCase, toPascalCase };