@izumisy-tailor/omakase-modules 0.2.0 → 0.4.0

package/src/config/module-loader.ts

@@ -1,21 +1,93 @@
-import { ConfiguredModule } from "../builder/helpers";
-import {
-  clearModuleRegistry,
-  getConfiguredModule,
-  registerConfiguredModules,
-} from "./module-registry";
+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>
@@ -33,29 +105,180 @@ 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;
   }) => {
     config: C;
   };
+  /**
+   * Get the tables from a dependency module by calling its factory function.
+   *
+   * 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
 ): LoadedModules => {
-  clearModuleRegistry();
-
   const emptyLoader = new ModuleLoader();
-  const modules = registerConfiguredModules(
-    configurator(emptyLoader)._getModules()
-  );
+  const modules = configurator(emptyLoader)._getModules();
 
   const loadedModules = modules.reduce<Record<string, ConfiguredModule<any>>>(
     (acc, module) => {
@@ -65,12 +288,12 @@ export const loadModules = (
     {}
   );
 
-  return {
+  const loadedModulesResult: LoadedModules = {
     loadedModules,
     loadConfig: <C extends Record<string, unknown>>(module: {
       packageName: string;
     }) => {
-      const loadedModule = getConfiguredModule(module.packageName);
+      const loadedModule = loadedModules[module.packageName];
       if (!loadedModule) {
         throw new Error(
           `Module "${module.packageName}" has not been configured. Ensure it is added via loadModules.`
@@ -81,5 +304,12 @@ export const loadModules = (
         config: loadedModule.moduleProps.config as C,
       };
     },
+    getTables: async <T>(
+      factory: (loadedModules: LoadedModules) => Promise<T>
+    ): Promise<T> => {
+      return factory(loadedModulesResult);
+    },
   };
+
+  return loadedModulesResult;
 };

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,20 +1,131 @@
 import path from "node:path";
-import { LoadedModules } from "../module-loader";
+import type { LoadedModules } from "../module-loader";
+import { generateWrapperFiles, OMAKASE_WRAPPER_DIR } from "./wrapper/generator";
 
-export const getModulesReference = (loadedModules: LoadedModules) => {
-  const modulePackageNames = Object.keys(loadedModules.loadedModules);
+/**
+ * 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.
+   *
+   * 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.
+   *
+   * 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;
+};
 
-  return {
-    tailordb: modulePackageNames.map((name) =>
-      path.join("node_modules", name, "src", "tailordb", "*.ts")
-    ),
+/**
+ * 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 = {}
+) => {
+  const { basePath = process.cwd(), silent = false } = options;
 
-    resolver: modulePackageNames.map((name) =>
-      path.join("node_modules", name, "src", "resolvers", "*.ts")
-    ),
+  // Log loaded modules information
+  const modulePackageNames = Object.keys(loadedModules.loadedModules);
+  if (!silent) {
+    console.log(`[omakase] Loaded ${modulePackageNames.length} module(s):\n`);
+    for (const name of modulePackageNames) {
+      console.log(` * ${name}`);
+    }
+    console.log("");
+  }
+
+  // Generate wrapper files and return paths to them
+  const wrapperPaths = await generateWrapperFiles(loadedModules, basePath);
 
-    executor: modulePackageNames.map((name) =>
-      path.join("node_modules", name, "src", "executors", "*.ts")
-    ),
+  return {
+    tailordb:
+      wrapperPaths.tailordb.length > 0
+        ? [path.join(OMAKASE_WRAPPER_DIR, "*", "tailordb", "*.ts")]
+        : [],
+    resolver:
+      wrapperPaths.resolver.length > 0
+        ? [path.join(OMAKASE_WRAPPER_DIR, "*", "resolvers", "*.ts")]
+        : [],
+    executor:
+      wrapperPaths.executor.length > 0
+        ? [path.join(OMAKASE_WRAPPER_DIR, "*", "executors", "*.ts")]
+        : [],
   };
 };