@izumisy-tailor/omakase-modules 0.3.0 → 0.4.1

package/src/config/module-loader.ts

@@ -1,16 +1,93 @@
-import { ConfiguredModule } from "../builder/helpers";
+import type { ConfiguredModule } from "../builder/helpers";
 
 /**
- * Module loader
- * Builder for registering modules within loadModules
+ * Module loader for registering and configuring modules.
+ *
+ * The `ModuleLoader` is used within the {@link loadModules} function to register
+ * configured modules. Modules can depend on each other, and the loader ensures
+ * proper dependency management.
+ *
+ * @example
+ * ```typescript
+ * import { loadModules } from "@izumisy-tailor/omakase-modules";
+ * import commerceModule from "omakase-module-commerce-core";
+ * import orderModule from "omakase-module-order";
+ * import inventoryModule from "omakase-module-inventory";
+ *
+ * export default loadModules((loader) => {
+ *   // Add a module without dependencies
+ *   const $commerce = loader.add(
+ *     commerceModule.configure({
+ *       config: {
+ *         dataModel: {
+ *           product: { docNumberPrefix: "PROD" },
+ *         },
+ *       },
+ *     })
+ *   );
+ *
+ *   // Add a module that depends on commerce
+ *   const $order = loader.add(
+ *     orderModule.configure({
+ *       config: { dataModel: {} },
+ *       dependencies: { commerce: $commerce },
+ *     })
+ *   );
+ *
+ *   // Add a module that depends on both commerce and order
+ *   loader.add(
+ *     inventoryModule.configure({
+ *       config: { dbNamespace: "main-db" },
+ *       dependencies: { commerce: $commerce, order: $order },
+ *     })
+ *   );
+ *
+ *   return loader;
+ * });
+ * ```
  */
 export class ModuleLoader {
   private modules: Array<ConfiguredModule<any>> = [];
 
   /**
-   * Add a module to the loader
-   * @param module Configured module
-   * @returns The added module (can be used as a dependency for other modules)
+   * Add a configured module to the loader.
+   *
+   * Returns the added module so it can be used as a dependency for other modules.
+   * This enables type-safe dependency wiring between modules.
+   *
+   * @param module - A configured module created by calling `moduleDefinition.configure()`
+   * @returns The same configured module, to be used as a dependency for other modules
+   *
+   * @example
+   * ```typescript
+   * loadModules((loader) => {
+   *   // Capture the returned value to use as a dependency
+   *   const $commerce = loader.add(
+   *     commerceModule.configure({
+   *       config: {
+   *         dataModel: {
+   *           product: {
+   *             docNumberPrefix: "PP-PROD",
+   *             customAttributes: {
+   *               customStatus: db.enum(["new", "used", "refurbished"]),
+   *             },
+   *           },
+   *         },
+   *       },
+   *     })
+   *   );
+   *
+   *   // Use the captured module as a dependency
+   *   loader.add(
+   *     orderModule.configure({
+   *       config: { dataModel: {} },
+   *       dependencies: { commerce: $commerce },
+   *     })
+   *   );
+   *
+   *   return loader;
+   * });
+   * ```
    */
   add<C extends Record<string, unknown>>(
     module: ConfiguredModule<C>
@@ -28,8 +105,59 @@ export class ModuleLoader {
   }
 }
 
+/**
+ * The result of loading modules, providing access to module configurations and tables.
+ *
+ * This type is returned by {@link loadModules} and passed to module factory functions.
+ * It provides utilities for:
+ * - Accessing configured module instances
+ * - Loading module configurations
+ * - Retrieving tables from dependency modules
+ *
+ * @example
+ * ```typescript
+ * // In tailor.config.ts - using getModulesReference with LoadedModules
+ * import { getModulesReference } from "@izumisy-tailor/omakase-modules/config/sdk";
+ * import modules from "./modules";
+ *
+ * const moduleReference = await getModulesReference(modules);
+ *
+ * export default defineConfig({
+ *   db: {
+ *     "main-db": {
+ *       files: ["./src/tailordb/*.ts", ...moduleReference.tailordb],
+ *     },
+ *   },
+ *   // ...
+ * });
+ * ```
+ */
 export type LoadedModules = {
   loadedModules: Record<string, ConfiguredModule<any>>;
+  /**
+   * Load the configuration for a specific module.
+   *
+   * Use this in module factory functions to access the user-provided configuration.
+   * Throws an error if the module has not been registered via `loadModules`.
+   *
+   * @param module - An object with `packageName` (typically the module definition)
+   * @returns An object containing the module's configuration
+   * @throws Error if the module has not been configured
+   *
+   * @example
+   * ```typescript
+   * // In a module's tailordb/index.ts
+   * import moduleDef from "../module";
+   *
+   * export default withModuleConfiguration(moduleDef, (context, loadedModules) => {
+   *   // Access this module's configuration
+   *   const { config } = loadedModules.loadConfig<ModuleConfig>(moduleDef);
+   *   const prefix = config.dataModel?.product?.docNumberPrefix ?? "PROD";
+   *
+   *   return { product: buildProductTable(context) };
+   * });
+   * ```
+   */
   loadConfig: <C extends Record<string, unknown>>(module: {
     packageName: string;
   }) => {
@@ -37,20 +165,114 @@ export type LoadedModules = {
   };
   /**
    * Get the tables from a dependency module by calling its factory function.
-   * This is used when an executor or resolver needs to reference tables from another module.
    *
-   * @param factory The factory function exported by the dependency module's tailordb/index.ts
-   * @returns The tables created by the factory
+   * Use this when a module needs to reference tables from another module,
+   * such as creating foreign key relationships or using shared types.
+   *
+   * @param factory - The factory function exported by the dependency module's `tailordb/index.ts`
+   * @returns A promise resolving to the tables created by the factory
+   *
+   * @example
+   * ```typescript
+   * // In inventory-module's tailordb/index.ts
+   * import commerceModuleTables from "omakase-module-commerce-core/backend/tailordb";
+   * import orderModuleTables from "omakase-module-order/backend/tailordb";
+   *
+   * export default withModuleConfiguration(
+   *   moduleDef,
+   *   async (context, loadedModules) => {
+   *     // Get tables from commerce module to reference product/productVariant
+   *     const { product, productVariant } = await loadedModules.getTables(
+   *       commerceModuleTables
+   *     );
+   *
+   *     // Get tables from order module to reference order
+   *     const { order } = await loadedModules.getTables(orderModuleTables);
+   *
+   *     // Use dependency tables when building this module's tables
+   *     const inventory = buildInventoryTable(context, { product, productVariant });
+   *     const inventoryTransaction = buildInventoryTransactionTable(context, {
+   *       inventory,
+   *       order,
+   *     });
+   *
+   *     return { inventory, inventoryTransaction };
+   *   }
+   * );
+   * ```
    */
   getTables: <T>(
     factory: (loadedModules: LoadedModules) => Promise<T>
   ) => Promise<T>;
+  /**
+   * Indicates this is a dev context created by loadModuleForDev.
+   * When true, wrapper generation uses local src paths instead of node_modules.
+   * @internal
+   */
+  __devContext?: {
+    /** The package name of the module being developed */
+    moduleName: string;
+  };
 };
 
 /**
- * Load modules with configuration
- * @param configurator Function that receives a loader, registers modules, and returns the loader
- * @returns Loaded modules and loadConfig function
+ * Load and configure modules for your Tailor application.
+ *
+ * This is the main entry point for setting up omakase modules. Use this function
+ * to register all modules your application needs, configure them with your settings,
+ * and wire up dependencies between modules.
+ *
+ * @param configurator - A function that receives a {@link ModuleLoader} and returns it after adding modules
+ * @returns A {@link LoadedModules} object containing all registered modules and utilities
+ *
+ * @example
+ * ```typescript
+ * // modules.ts - Define your module configuration
+ * import { loadModules } from "@izumisy-tailor/omakase-modules";
+ * import { db } from "@tailor-platform/sdk";
+ * import commerceModule from "omakase-module-commerce-core";
+ * import orderModule from "omakase-module-order";
+ * import inventoryModule from "omakase-module-inventory";
+ *
+ * export default loadModules((loader) => {
+ *   // Configure and add the commerce module
+ *   const $commerce = loader.add(
+ *     commerceModule.configure({
+ *       config: {
+ *         dataModel: {
+ *           product: {
+ *             docNumberPrefix: "PP-PROD",
+ *             customAttributes: {
+ *               customStatus: db.enum(["new", "used", "refurbished"]),
+ *             },
+ *           },
+ *         },
+ *       },
+ *     })
+ *   );
+ *
+ *   // Configure order module with commerce as a dependency
+ *   const $order = loader.add(
+ *     orderModule.configure({
+ *       config: { dataModel: {} },
+ *       dependencies: { commerce: $commerce },
+ *     })
+ *   );
+ *
+ *   // Configure inventory module with both dependencies
+ *   loader.add(
+ *     inventoryModule.configure({
+ *       config: {
+ *         dbNamespace: "main-db",
+ *         invantoryBootstrapBaseValue: 300,
+ *       },
+ *       dependencies: { commerce: $commerce, order: $order },
+ *     })
+ *   );
+ *
+ *   return loader;
+ * });
+ * ```
  */
 export const loadModules = (
   configurator: (loader: ModuleLoader) => ModuleLoader

package/src/config/sdk/dev-context.ts

@@ -0,0 +1,82 @@
+import { loadModules, type LoadedModules } from "../module-loader";
+import type { DefinedModule, DependencyModules } from "../../builder/helpers";
+
+/**
+ * Creates a LoadedModules context for individual module development.
+ *
+ * This allows using `getModulesReference` in a module's own `tailor.config.ts`,
+ * enabling the kysely-type generator to work during module development.
+ *
+ * Dependencies declared in the module's `defineModule` are automatically
+ * registered with default (empty) configurations.
+ *
+ * @param module The module being developed
+ * @param config Optional development configuration. If omitted, uses module.devConfig.
+ * @returns A LoadedModules object that can be passed to getModulesReference
+ *
+ * @example
+ * ```typescript
+ * // tailor.config.ts
+ * import { loadModuleForDev, getModulesReference } from "@izumisy-tailor/omakase-modules/config/sdk";
+ * import inventoryModule from "./src/module";
+ *
+ * const modules = loadModuleForDev(inventoryModule);
+ * const moduleReference = await getModulesReference(modules);
+ *
+ * export default defineConfig({ ... });
+ * ```
+ */
+export const loadModuleForDev = <
+  C extends Record<string, unknown>,
+  Tables extends Record<string, unknown>,
+  Deps extends DependencyModules
+>(
+  module: DefinedModule<C, Tables, Deps>,
+  config?: C
+): LoadedModules => {
+  // Use provided config, fall back to module's devConfig, or use empty object as default
+  const resolvedConfig = config ?? module.devConfig ?? ({} as C);
+
+  const modules = loadModules((loader) => {
+    // Recursively register all dependency modules with default config
+    const registerDependencies = (deps: DependencyModules) => {
+      for (const dep of Object.values(deps)) {
+        if (!dep) continue; // Skip empty dependency marker
+        // First register transitive dependencies
+        if (dep.dependencies && Object.keys(dep.dependencies).length > 0) {
+          registerDependencies(dep.dependencies);
+        }
+        // Then register this dependency with empty config
+        // For dev context, we use type assertion since dependencies are auto-resolved
+        loader.add(
+          (
+            dep.configure as (props: { config: Record<string, unknown> }) => any
+          )({ config: {} })
+        );
+      }
+    };
+
+    // Register all dependencies first
+    if (module.dependencies && Object.keys(module.dependencies).length > 0) {
+      registerDependencies(module.dependencies);
+    }
+
+    // Register the main module being developed
+    // For dev context, we don't need to pass dependencies
+    loader.add(
+      (module.configure as (props: { config: C }) => any)({
+        config: resolvedConfig,
+      })
+    );
+
+    return loader;
+  });
+
+  // Mark this as a dev context with the module name being developed
+  return {
+    ...modules,
+    __devContext: {
+      moduleName: module.packageName,
+    },
+  };
+};

package/src/config/sdk/index.ts

@@ -1 +1,2 @@
-export { getModulesReference } from "./paths";
+export { getModulesReference, type GetModulesReferenceOptions } from "./paths";
+export { loadModuleForDev } from "./dev-context";

package/src/config/sdk/paths.ts

@@ -1,18 +1,100 @@
 import path from "node:path";
-import { LoadedModules } from "../module-loader";
+import type { LoadedModules } from "../module-loader";
 import { generateWrapperFiles, OMAKASE_WRAPPER_DIR } from "./wrapper/generator";
 
+/**
+ * Options for configuring {@link getModulesReference} behavior.
+ *
+ * @example
+ * ```typescript
+ * const moduleReference = await getModulesReference(modules, {
+ *   basePath: "/custom/path",
+ *   silent: true, // Suppress console output
+ * });
+ * ```
+ */
 export type GetModulesReferenceOptions = {
   /**
-   * Base path for the application (defaults to process.cwd())
+   * Base path for the application.
+   *
+   * This determines where wrapper files are generated and where module
+   * paths are resolved from. Defaults to `process.cwd()`.
+   *
+   * @default process.cwd()
    */
   basePath?: string;
   /**
-   * Whether to suppress log output (defaults to false)
+   * Whether to suppress log output.
+   *
+   * When `true`, no console output will be printed during module loading.
+   * Useful for testing or when you want cleaner build output.
+   *
+   * @default false
    */
   silent?: boolean;
 };
 
+/**
+ * Get file path patterns for modules to use in Tailor configuration.
+ *
+ * This function processes your loaded modules and returns glob patterns
+ * that can be spread into your `defineConfig`. It handles all the necessary
+ * setup to make module TailorDB types, resolvers, and executors available
+ * to Tailor's configuration system.
+ *
+ * @param loadedModules - The result of calling `loadModules()`
+ * @param options - Optional configuration for path resolution and logging
+ * @returns An object containing glob patterns for `tailordb`, `resolver`, and `executor` files
+ *
+ * @example
+ * ```typescript
+ * // tailor.config.ts
+ * import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
+ * import { getModulesReference } from "@izumisy-tailor/omakase-modules/config/sdk";
+ * import modules from "./modules";
+ *
+ * // Get module path patterns
+ * const moduleReference = await getModulesReference(modules);
+ *
+ * export default defineConfig({
+ *   name: "my-app",
+ *
+ *   // Spread module paths alongside your local files
+ *   db: {
+ *     "main-db": {
+ *       files: ["./src/tailordb/*.ts", ...moduleReference.tailordb],
+ *     },
+ *   },
+ *
+ *   resolver: {
+ *     "main-pipeline": {
+ *       files: ["./src/resolvers/*.ts", ...moduleReference.resolver],
+ *     },
+ *   },
+ *
+ *   executor: {
+ *     files: ["./src/executors/*.ts", ...moduleReference.executor],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const moduleReference = await getModulesReference(modules, {
+ *   basePath: import.meta.dirname, // Use ESM module directory
+ *   silent: true, // No console output
+ * });
+ * ```
+ *
+ * @remarks
+ * The returned object contains three arrays:
+ * - `tailordb` - Paths to TailorDB type definitions from modules
+ * - `resolver` - Paths to GraphQL resolver definitions from modules
+ * - `executor` - Paths to event executor definitions from modules
+ *
+ * If a module has no files of a certain type, that array will be empty.
+ */
 export const getModulesReference = async (
   loadedModules: LoadedModules,
   options: GetModulesReferenceOptions = {}

package/src/config/sdk/wrapper/base.ts

@@ -2,12 +2,29 @@ import dedent from "dedent";
 import fs from "node:fs/promises";
 import path from "node:path";
 
+/**
+ * Sanitize a package name for use in file paths.
+ * Removes leading @ and replaces / with __ to create a flat directory structure.
+ * e.g., "@izumisy-tailor/hoge-modules" -> "izumisy-tailor__hoge-modules"
+ */
+export const sanitizePackageName = (packageName: string): string => {
+  return packageName.replace(/^@/, "").replace(/\//g, "__");
+};
+
 /**
  * Path alias for importing modules config.
  * App's tsconfig.json should have: "@omakase-modules/config": ["./modules"]
+ * Module's tsconfig.json should have: "@omakase-modules/config": ["./src/module"]
  */
 export const MODULES_IMPORT_PATH = "@omakase-modules/config";
 
+/**
+ * Relative path from wrapper files to dev-modules.ts for dev context.
+ * Wrapper files are at: .tailor-sdk/.omakase/{packageName}/{category}/file.ts
+ * dev-modules.ts is at: .tailor-sdk/.omakase/dev-modules.ts
+ */
+export const DEV_MODULES_RELATIVE_PATH = "../../dev-modules";
+
 /**
  * Category types for wrapper generation
  */
@@ -17,10 +34,33 @@ export type Category = "tailordb" | "resolvers" | "executors";
  * Abstract base class for category-specific wrapper generation
  */
 export abstract class WrapperStrategy {
+  /**
+   * Whether this module is being developed locally (not from node_modules)
+   */
+  protected readonly isLocalModule: boolean;
+
+  /**
+   * The import path for modules (either alias or relative path for dev context)
+   */
+  protected readonly modulesImportPath: string;
+
   constructor(
     protected readonly packageName: string,
-    protected readonly basePath: string
-  ) {}
+    protected readonly basePath: string,
+    /**
+     * The package name of the module being developed locally.
+     * When set, the strategy will use local src paths for this module
+     * and relative import path for dev-modules.ts.
+     */
+    protected readonly devModuleName?: string
+  ) {
+    this.isLocalModule = devModuleName === packageName;
+    // In dev context, use relative path to auto-generated dev-modules.ts
+    // In app context, use the @omakase-modules/config alias
+    this.modulesImportPath = devModuleName
+      ? DEV_MODULES_RELATIVE_PATH
+      : MODULES_IMPORT_PATH;
+  }
 
   /**
    * The category this strategy handles
@@ -33,10 +73,18 @@ export abstract class WrapperStrategy {
   abstract filterFiles(files: string[]): string[];
 
   /**
-   * Get the module export path
+   * Get the module export path for npm packages
    */
   abstract getExportPath(fileName: string): string;
 
+  /**
+   * Get the local export path for the module being developed.
+   * Uses @/ alias which maps to src/ in module's tsconfig.
+   */
+  getLocalExportPath(fileName: string): string {
+    return `@/${this.category}/${fileName.replace(/\.ts$/, "")}`;
+  }
+
   /**
    * Generate the export statements using the factory result.
    * Default implementation exports the result as default export.
@@ -62,8 +110,8 @@ export abstract class WrapperStrategy {
        * ensuring proper configuration injection and avoiding tree-shaking issues.
        */
 
-      // Import the loadModules result from the app's modules.ts
-      import modules from "${MODULES_IMPORT_PATH}";
+      // Import the loadModules result from the app's modules.ts (or auto-generated dev-modules.ts)
+      import modules from "${this.modulesImportPath}";
 
       // Import the factory function from the module
       import createFactory from "${moduleExportPath}";
@@ -79,15 +127,17 @@ export abstract class WrapperStrategy {
    * Generate wrapper files for this category
    */
   async generateFiles(wrapperDir: string): Promise<string[]> {
-    const sourcePath = path.join(
-      this.basePath,
-      "node_modules",
-      this.packageName,
-      "src",
-      this.category
-    );
+    // Determine source path based on whether this is a local module or a dependency
+    const sourcePath = this.isLocalModule
+      ? path.join(this.basePath, "src", this.category)
+      : path.join(
+          this.basePath,
+          "node_modules",
+          this.packageName,
+          "src",
+          this.category
+        );
 
-    // Check if the source directory exists
     if (!(await this.exists(sourcePath))) {
       return [];
     }
@@ -113,13 +163,16 @@ export abstract class WrapperStrategy {
   ): Promise<string> {
     const categoryWrapperDir = path.join(
       wrapperDir,
-      this.packageName,
+      sanitizePackageName(this.packageName),
       this.category
     );
     await fs.mkdir(categoryWrapperDir, { recursive: true });
 
     const wrapperFilePath = path.join(categoryWrapperDir, fileName);
-    const moduleExportPath = this.getExportPath(fileName);
+    // Use local path for the module being developed, npm path for dependencies
+    const moduleExportPath = this.isLocalModule
+      ? this.getLocalExportPath(fileName)
+      : this.getExportPath(fileName);
     const content = await this.generateContent(moduleExportPath);
 
     await fs.writeFile(wrapperFilePath, content, "utf-8");

package/src/config/sdk/wrapper/generator.ts

@@ -1,6 +1,7 @@
+import dedent from "dedent";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { LoadedModules } from "../../module-loader";
+import type { LoadedModules } from "../../module-loader";
 import { createStrategy } from "./strategies";
 
 /**
@@ -8,10 +9,35 @@ import { createStrategy } from "./strategies";
  */
 export const OMAKASE_WRAPPER_DIR = ".tailor-sdk/.omakase";
 
+/**
+ * Generates the dev-modules.ts file for module development.
+ * This file is auto-generated and imports the module via @omakase-modules/config alias,
+ * then calls loadModuleForDev to create the LoadedModules context.
+ */
+const generateDevModulesFile = async (wrapperDir: string) => {
+  const devModulesPath = path.join(wrapperDir, "dev-modules.ts");
+
+  const content = dedent`
+    /**
+     * Auto-generated dev-modules file by @izumisy-tailor/omakase-modules
+     * DO NOT EDIT THIS FILE MANUALLY
+     *
+     * This file imports the module definition and creates a LoadedModules context
+     * for wrapper files to use during module development.
+     */
+    import { loadModuleForDev } from "@izumisy-tailor/omakase-modules/config/sdk";
+    import module from "@omakase-modules/config";
+
+    export default loadModuleForDev(module);
+  `;
+
+  await fs.writeFile(devModulesPath, content, "utf-8");
+};
+
 /**
  * Generates wrapper files for each module's tailordb, executor, and resolver files.
  * These wrappers import the factory functions from modules and call them with
- * the loadModules result from the app's modules.ts.
+ * the loadModules result from the app's modules.ts (or dev-modules.ts for module development).
  */
 export const generateWrapperFiles = async (
   loadedModules: LoadedModules,
@@ -28,14 +54,25 @@ export const generateWrapperFiles = async (
     // Directory doesn't exist, no need to clean up
   }
 
+  // Ensure wrapper directory exists
+  await fs.mkdir(wrapperDir, { recursive: true });
+
   const result = {
     tailordb: [] as string[],
     resolver: [] as string[],
     executor: [] as string[],
   };
 
+  // Get dev module name if this is a dev context
+  const devModuleName = loadedModules.__devContext?.moduleName;
+
+  // Generate dev-modules.ts for dev context
+  if (devModuleName) {
+    await generateDevModulesFile(wrapperDir);
+  }
+
   for (const packageName of modulePackageNames) {
-    const strategyFor = createStrategy(packageName, basePath);
+    const strategyFor = createStrategy(packageName, basePath, devModuleName);
 
     result.tailordb.push(
       ...(await strategyFor("tailordb").generateFiles(wrapperDir))