@izumisy-tailor/omakase-modules 0.2.0 → 0.4.0

package/package.json

@@ -1,26 +1,17 @@
 {
   "name": "@izumisy-tailor/omakase-modules",
   "private": false,
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Modularization mechanism for Tailor Platform application powered by Tailor SDK",
   "type": "module",
   "files": [
-    "src",
-    "docs"
+    "docs/generated",
+    "src"
   ],
   "exports": {
-    ".": {
-      "default": "./src/config/index.ts"
-    },
-    "./config/sdk": {
-      "default": "./src/config/sdk/index.ts"
-    },
-    "./builder": {
-      "default": "./src/builder/index.ts"
-    },
-    "./config/loader": {
-      "default": "./src/stub-loader/index.ts"
-    }
+    ".": "./src/config/index.ts",
+    "./config/sdk": "./src/config/sdk/index.ts",
+    "./builder": "./src/builder/index.ts"
   },
   "keywords": [
     "tailor-platform",
@@ -32,13 +23,21 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "tsdown": "^0.18.0",
-    "typescript": "^5"
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "^5",
+    "vite-tsconfig-paths": "^6.0.3",
+    "vitest": "^4.0.16"
   },
   "peerDependencies": {
     "@tailor-platform/sdk": "^0.20.0"
   },
+  "dependencies": {
+    "dedent": "^1.7.1"
+  },
   "scripts": {
-    "type-check": "tsc"
+    "type-check": "tsc",
+    "test": "vitest run",
+    "docsgen": "typedoc"
   }
 }

package/src/builder/helpers.ts

@@ -1,51 +1,411 @@
-type ModuleBuilderProps<C extends Record<string, unknown>> = {
-  config: C;
-};
+import type { TailorDBType } from "@tailor-platform/sdk";
+
+/**
+ * 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
+> = {
+  /**
+   * Adds dependencies to the module definition.
+   * The Deps type is automatically inferred from the record.
+   *
+   * @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>;
   /**
-   * The package name of the module.
+   * 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();
    *
-   * This is required to be the same as the name field in package.json
+   * // 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,
-      };
-    },
-  };
-};
-
-export type ModuleDependency<T extends DefinedModule<any, any>> =
-  T extends DefinedModule<infer C, infer Tables>
-    ? ConfiguredModule<C> & {
-        readonly __tablesBrand?: Tables;
-      }
-    : never;
+    dependencies: deps,
+    devConfig,
+    configure: (props) => ({
+      packageName: baseProps.packageName,
+      moduleProps: { config: props.config },
+    }),
+  });
+
+  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
+// ============================================================================
+
+/**
+ * Derives a tables type from a tableNames array.
+ * Use this to avoid manually defining a separate Tables type.
+ *
+ * @example
+ * ```typescript
+ * export const tableNames = ["product", "category"] as const;
+ * type MyTables = TablesFromNames<typeof tableNames>;
+ * // Result: { product: TailorDBType; category: TailorDBType }
+ * ```
+ */
+export type TablesFromNames<T extends readonly string[]> = {
+  [K in T[number]]: TailorDBType;
+};
+
+/**
+ * Context passed to table builder functions.
+ * Provides access to the module's configuration.
+ *
+ * @example
+ * ```typescript
+ * export const buildProductTable = (
+ *   { config }: ModuleFactoryContext<ModuleConfig>,
+ *   deps: { category: TailorDBType }
+ * ) => {
+ *   const prefix = config.dataModel?.product?.docNumberPrefix ?? "PROD";
+ *   return db.type("Product", { ... });
+ * };
+ * ```
+ */
+export type ModuleFactoryContext<C extends Record<string, unknown>> = {
+  config: C;
+};

package/src/builder/index.ts

@@ -2,6 +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,34 +1,47 @@
-import type { ModuleConfigLoaderReturn } from "../stub-loader/interface";
-import type { DefinedModule } from "./helpers";
-
-type ModuleFactoryContext<C extends Record<string, unknown>> = Awaited<
-  ModuleConfigLoaderReturn<C>
->;
+import type { LoadedModules } from "../config/module-loader";
+import type { DefinedModule, ModuleFactoryContext } from "./helpers";
 
 /**
- * Load a module's configuration, define something.
+ * Define module exports that depend on configuration from loadModules.
+ *
+ * This function returns a factory function that takes LoadedModules as input
+ * and produces the configured exports. The wrapper files generated by
+ * getModulesReference will call this factory with the app's loadModules result.
+ *
+ * @example
+ * ```typescript
+ * // In module's tailordb/index.ts
+ * export default withModuleConfiguration(moduleDef, (context) => {
+ *   const inventory = buildInventoryTable(context);
+ *   return { inventory };
+ * });
+ *
+ * // In module's executors that need dependency module tables:
+ * export default withModuleConfiguration(moduleDef, async (context, loadedModules) => {
+ *   const { productVariant } = await loadedModules.getTables(commerceModuleTables);
+ *   return createExecutor({ ... });
+ * });
  *
- * THis is a low-level utility composed by a specific builder function.
+ * // The wrapper file will call it like:
+ * // import factory from "module/backend/tailordb";
+ * // import modules from "../../modules";
+ * // export default await factory(modules);
+ * ```
  */
-export const withModuleConfiguration = async <
+export const withModuleConfiguration = <
   C extends Record<string, unknown>,
   Tables extends Record<string, unknown>,
+  Deps extends Record<string, any>,
   Result
 >(
-  module: DefinedModule<C, Tables>,
-  factory: (context: ModuleFactoryContext<C>) => Result | Promise<Result>
-) => {
-  /**
-   * This import intentionally uses a module path instead of a package path
-   * to let the app override the implementation via tsconfig paths.
-   *
-   * For more details, see `moduleConfigLoader` in `./src/stub-loader/interface.ts`.
-   *
-   * Dynamic import is also important here to avoid "cannot acess before initialization" error.
-   */
-  const { default: configLoader } = await import(
-    "@izumisy-tailor/omakase-modules/config/loader"
-  );
-  const moduleState = await configLoader.loadConfig(module);
-  return await factory(moduleState);
+  module: DefinedModule<C, Tables, Deps>,
+  factory: (
+    context: ModuleFactoryContext<C>,
+    loadedModules: LoadedModules
+  ) => Result | Promise<Result>
+): ((loadedModules: LoadedModules) => Promise<Result>) => {
+  return async (loadedModules: LoadedModules) => {
+    const moduleState = loadedModules.loadConfig<C>(module);
+    return await factory(moduleState, loadedModules);
+  };
 };