@izumisy-tailor/omakase-modules 0.3.0 → 0.4.0

package/src/builder/helpers.ts

@@ -1,56 +1,376 @@
 import type { TailorDBType } from "@tailor-platform/sdk";
 
-type ModuleBuilderProps<C extends Record<string, unknown>> = {
-  config: C;
-};
+/**
+ * Represents a module with no dependencies.
+ *
+ * This is a branded type used internally to distinguish modules
+ * that have no dependencies from those that do. When defining a module
+ * without dependencies, you don't need to use this type directly.
+ *
+ * @example
+ * ```typescript
+ * // Modules without dependencies don't need to specify this type
+ * export default defineModule<MyConfig, MyTables>({
+ *   packageName: "my-module",
+ * }).build();
+ * ```
+ */
+export type EmptyDependencies = { readonly __empty?: never };
 
+/**
+ * Properties required when configuring a module via `configure()`.
+ *
+ * The shape of this type varies based on whether the module has dependencies:
+ * - **Without dependencies**: `{ config: C }`
+ * - **With dependencies**: `{ config: C; dependencies: ConfiguredDependencies<Deps> }`
+ *
+ * @example
+ * ```typescript
+ * // Module without dependencies
+ * myModule.configure({
+ *   config: { dbNamespace: "main-db" },
+ * });
+ *
+ * // Module with dependencies
+ * inventoryModule.configure({
+ *   config: { dbNamespace: "main-db" },
+ *   dependencies: {
+ *     commerce: $commerceModule,
+ *     order: $orderModule,
+ *   },
+ * });
+ * ```
+ */
+export type ModuleBuilderProps<
+  /**
+   * The configuration type for the module
+   */
+  C extends Record<string, unknown>,
+  /**
+   * The dependency modules record type
+   */
+  Deps extends DependencyModules
+> = Deps extends EmptyDependencies
+  ? { config: C }
+  : { config: C; dependencies: ConfiguredDependencies<Deps> };
+
+/**
+ * A module that has been configured with specific settings.
+ *
+ * This type represents the result of calling `configure()` on a {@link DefinedModule}.
+ * Configured modules can be passed as dependencies to other modules or used
+ * directly in your application's Tailor configuration.
+ *
+ * @example
+ * ```typescript
+ * // Create a configured module
+ * const $commerceModule = commerceModule.configure({
+ *   config: { dbNamespace: "main-db" },
+ * });
+ *
+ * // Use as a dependency in another module
+ * const $inventoryModule = inventoryModule.configure({
+ *   config: { dbNamespace: "main-db" },
+ *   dependencies: {
+ *     commerce: $commerceModule,
+ *   },
+ * });
+ * ```
+ */
 export type ConfiguredModule<
+  /**
+   * The configuration type that was used to configure the module
+   */
   C extends Record<string, unknown> = Record<string, unknown>
 > = {
   packageName: string;
-  moduleProps: ModuleBuilderProps<C>;
+  moduleProps: { config: C };
+  /**
+   * @internal Brand for config type identification in dependency checking.
+   */
+  readonly __configBrand?: C;
+};
+
+/**
+ * A record of module dependencies or an empty dependency set.
+ *
+ * This type represents the dependencies that a module can declare.
+ * It is either a record mapping dependency names to {@link AnyDefinedModule},
+ * or {@link EmptyDependencies} for modules without dependencies.
+ *
+ * @example
+ * ```typescript
+ * // Used internally when defining module dependencies
+ * defineModule<MyConfig, MyTables>({
+ *   packageName: "my-module",
+ * }).withDependencies({
+ *   commerce: commerceModule,  // Record<string, AnyDefinedModule>
+ *   order: orderModule,
+ * }).build();
+ * ```
+ */
+export type DependencyModules =
+  | Record<string, AnyDefinedModule>
+  | EmptyDependencies;
+
+/**
+ * A loosely-typed representation of any defined module.
+ *
+ * This type is used in dependency records where the exact type parameters
+ * of the module are not important. It provides the minimal interface needed
+ * to work with modules as dependencies.
+ *
+ * For strongly-typed module definitions, use {@link DefinedModule} instead.
+ *
+ * @see {@link DefinedModule} for the fully-typed module definition.
+ */
+export type AnyDefinedModule = {
+  packageName: string;
+  dependencies: Record<string, any>;
+  configure: (props: any) => ConfiguredModule<any>;
+
+  /**
+   * @internal Brand for tables type identification in helper utilities.
+   */
+  readonly __tablesBrand?: any;
+
+  /**
+   * @internal Brand for config type identification in dependency checking.
+   */
+  readonly __configBrand?: any;
+};
+
+/**
+ * Transforms a record of {@link DefinedModule}s into a record of {@link ConfiguredModule}s.
+ *
+ * This utility type is used to derive the expected shape of the `dependencies`
+ * property when configuring a module that has dependencies. It preserves
+ * the exact configuration type for each dependency module.
+ *
+ * @example
+ * ```typescript
+ * // When a module is defined with dependencies:
+ * defineModule<MyConfig, MyTables>({
+ *   packageName: "my-module",
+ * }).withDependencies({
+ *   commerce: commerceModule,
+ *   order: orderModule,
+ * }).build();
+ *
+ * // The configure() method will expect:
+ * myModule.configure({
+ *   config: { ... },
+ *   dependencies: {
+ *     commerce: ConfiguredModule<CommerceConfig>,
+ *     order: ConfiguredModule<OrderConfig>,
+ *   },
+ * });
+ * ```
+ */
+export type ConfiguredDependencies<
+  /**
+   * The dependency modules record to transform
+   */
+  Deps extends DependencyModules
+> = {
+  [K in keyof Deps as K extends "__empty" ? never : K]: Deps[K] extends {
+    readonly __configBrand?: infer C;
+  }
+    ? C extends Record<string, unknown>
+      ? ConfiguredModule<C>
+      : never
+    : never;
 };
 
+/**
+ * A fully defined, reusable module that can be configured and composed.
+ *
+ * This is the primary type for modules created with {@link defineModule}.
+ * A `DefinedModule` encapsulates:
+ * - The module's package name for identification
+ * - Its dependencies on other modules
+ * - A `configure()` method to create a {@link ConfiguredModule}
+ * - Optional development configuration for local testing
+ *
+ * @example
+ * ```typescript
+ * // Define a module
+ * const inventoryModule = defineModule<InventoryConfig, InventoryTables>({
+ *   packageName: "inventory-module",
+ * })
+ *   .withDependencies({ commerce: commerceModule })
+ *   .withDevConfig({ dbNamespace: "dev" })
+ *   .build();
+ *
+ * // Configure the module for use
+ * const $inventory = inventoryModule.configure({
+ *   config: { dbNamespace: "production" },
+ *   dependencies: {
+ *     commerce: $commerceModule,
+ *   },
+ * });
+ * ```
+ */
 export type DefinedModule<
+  /**
+   * The configuration schema for the module
+   */
   C extends Record<string, unknown>,
-  Tables extends Record<string, unknown> = Record<string, unknown>
+  /**
+   * The TailorDB table definitions exported by the module
+   */
+  Tables extends Record<string, unknown> = Record<string, unknown>,
+  /**
+   * The dependency modules this module requires
+   */
+  Deps extends DependencyModules = EmptyDependencies
 > = {
   packageName: string;
-  configure: (props: ModuleBuilderProps<C>) => ConfiguredModule<C>;
+  dependencies: Deps;
+  configure: (props: ModuleBuilderProps<C, Deps>) => ConfiguredModule<C>;
+  /**
+   * Default configuration for module development.
+   * Used by loadModuleForDev when no config is provided.
+   */
+  devConfig?: C;
   /**
    * @internal Type-only hook so that table shapes flow through helper utilities.
    */
   readonly __tablesBrand?: Tables;
+  /**
+   * @internal Brand for config type identification in dependency checking.
+   */
+  readonly __configBrand?: C;
 };
 
-export const defineModule = <
+/**
+ * Intermediate builder type returned by defineModule.
+ * Use .withDependencies() to add dependencies, then call .build() to finalize.
+ * Modules without dependencies can call .build() directly.
+ */
+export type ModuleBuilder<
   C extends Record<string, unknown>,
-  Tables extends Record<string, unknown> = Record<string, unknown>
->(baseProps: {
+  Tables extends Record<string, unknown>,
+  Deps extends DependencyModules = EmptyDependencies
+> = {
   /**
-   * The package name of the module.
+   * Adds dependencies to the module definition.
+   * The Deps type is automatically inferred from the record.
    *
-   * This is required to be the same as the name field in package.json
+   * @example
+   * ```typescript
+   * export default defineModule<ModuleConfig, Tables>({
+   *   packageName: "my-module",
+   * }).withDependencies({
+   *   commerce: commerceModule,
+   *   order: orderModule,
+   * }).build();
+   * ```
    */
+  withDependencies: <const NewDeps extends DependencyModules>(
+    deps: NewDeps
+  ) => ModuleBuilder<C, Tables, NewDeps>;
+  /**
+   * Sets the default configuration for module development.
+   * This config is used by loadModuleForDev when no config is provided.
+   *
+   * @example
+   * ```typescript
+   * export default defineModule<ModuleConfig, Tables>({
+   *   packageName: "my-module",
+   * }).withDevConfig({
+   *   dbNamespace: "main-db",
+   * }).build();
+   * ```
+   */
+  withDevConfig: (config: C) => ModuleBuilder<C, Tables, Deps>;
+  /**
+   * Finalizes the module definition and returns the DefinedModule.
+   * This must be called at the end of the builder chain to get the actual module.
+   *
+   * @example
+   * ```typescript
+   * // Without dependencies
+   * export default defineModule<ModuleConfig, Tables>({
+   *   packageName: "my-module",
+   * }).build();
+   *
+   * // With dependencies and dev config
+   * export default defineModule<ModuleConfig, Tables>({
+   *   packageName: "my-module",
+   * })
+   *   .withDependencies({ commerce: commerceModule })
+   *   .withDevConfig({ dbNamespace: "dev" })
+   *   .build();
+   * ```
+   */
+  build: () => DefinedModule<C, Tables, Deps>;
+};
+
+/**
+ * Defines a reusable module with optional dependencies on other modules.
+ *
+ * @example
+ * ```typescript
+ * // Module without dependencies
+ * export default defineModule<ModuleConfig, Tables>({
+ *   packageName: "my-module",
+ * }).build();
+ *
+ * // Module with dependencies - Deps type is automatically inferred
+ * import commerceModule from "omakase-module-commerce-core";
+ * import orderModule from "omakase-module-order";
+ *
+ * export default defineModule<ModuleConfig, Tables>({
+ *   packageName: "my-module",
+ * }).withDependencies({
+ *   commerce: commerceModule,
+ *   order: orderModule,
+ * }).build();
+ *
+ * // When configuring a module with dependencies, pass them as a record:
+ * inventoryModule.configure({
+ *   config: { dbNamespace: "main-db" },
+ *   dependencies: {
+ *     commerce: $commerceModule,
+ *     order: $orderModule,
+ *   },
+ * });
+ * ```
+ */
+export const defineModule = <
+  C extends Record<string, unknown>,
+  Tables extends Record<string, unknown> = Record<string, unknown>
+>(baseProps: {
   packageName: string;
-}): DefinedModule<C, Tables> => {
-  return {
+}): ModuleBuilder<C, Tables> => {
+  const createModule = <Deps extends DependencyModules>(
+    deps: Deps,
+    devConfig?: C
+  ): DefinedModule<C, Tables, Deps> => ({
     packageName: baseProps.packageName,
-    configure: (props) => {
-      return {
-        packageName: baseProps.packageName,
-        moduleProps: props,
-      };
-    },
-  };
-};
+    dependencies: deps,
+    devConfig,
+    configure: (props) => ({
+      packageName: baseProps.packageName,
+      moduleProps: { config: props.config },
+    }),
+  });
 
-export type ModuleDependency<T extends DefinedModule<any, any>> =
-  T extends DefinedModule<infer C, infer Tables>
-    ? ConfiguredModule<C> & {
-        readonly __tablesBrand?: Tables;
-      }
-    : never;
+  const createBuilder = <Deps extends DependencyModules>(
+    deps: Deps,
+    devConfig?: C
+  ): ModuleBuilder<C, Tables, Deps> => ({
+    withDependencies: <const NewDeps extends DependencyModules>(
+      newDeps: NewDeps
+    ): ModuleBuilder<C, Tables, NewDeps> => createBuilder(newDeps, devConfig),
+    withDevConfig: (config: C): ModuleBuilder<C, Tables, Deps> =>
+      createBuilder(deps, config),
+    build: (): DefinedModule<C, Tables, Deps> => createModule(deps, devConfig),
+  });
+
+  return createBuilder({} as EmptyDependencies);
+};
 
 // ============================================================================
 // Utility Types for Module Development

package/src/builder/index.ts

@@ -2,8 +2,13 @@ export {
   defineModule,
   type ConfiguredModule,
   type DefinedModule,
-  type ModuleDependency,
   type TablesFromNames,
   type ModuleFactoryContext,
+  type DependencyModules,
+  type EmptyDependencies,
+  type ModuleBuilder,
+  type AnyDefinedModule,
+  type ModuleBuilderProps,
+  type ConfiguredDependencies,
 } from "./helpers";
 export { withModuleConfiguration } from "./register";

package/src/builder/register.ts

@@ -1,9 +1,5 @@
 import type { LoadedModules } from "../config/module-loader";
-import type { DefinedModule } from "./helpers";
-
-type ModuleFactoryContext<C extends Record<string, unknown>> = {
-  config: C;
-};
+import type { DefinedModule, ModuleFactoryContext } from "./helpers";
 
 /**
  * Define module exports that depend on configuration from loadModules.
@@ -35,9 +31,10 @@ type ModuleFactoryContext<C extends Record<string, unknown>> = {
 export const withModuleConfiguration = <
   C extends Record<string, unknown>,
   Tables extends Record<string, unknown>,
+  Deps extends Record<string, any>,
   Result
 >(
-  module: DefinedModule<C, Tables>,
+  module: DefinedModule<C, Tables, Deps>,
   factory: (
     context: ModuleFactoryContext<C>,
     loadedModules: LoadedModules