@izumisy-tailor/omakase-modules 0.2.0 → 0.3.0

package/README.md

@@ -45,15 +45,3 @@ pnpm add @izumisy-tailor/omakase-modules
 ### `@izumisy-tailor/omakase-modules/config/sdk`
 
 - `getModulesReference(loadedModules)` - Generate file path references for `tailor.config.ts`
-
-## Project Structure
-
-```
-examples/
-  commerce-core-module/     # E-commerce core module (Product, Customer, etc.)
-  order-module/             # Order management module
-  inventory-module/         # Inventory management module
-  basic-app/                # Application using the above modules
-packages/
-  core/                     # omakase-modules core package
-```

package/docs/tutorials/creating-modules.md

@@ -11,11 +11,10 @@ my-module/
   package.json
   tsconfig.json
   src/
-    module.ts           # Module definition
+    module.ts           # Module definition and table types export
     types.ts            # Configuration types
     tailordb/
-      index.ts          # TailorDB exports
-      context.ts        # Type definitions for tables
+      index.ts          # TailorDB exports with tableNames
       my-table.ts       # Table builders
     resolvers/
       my-resolver.ts
@@ -29,17 +28,20 @@ Create the module definition with `defineModule`:
 
 ```typescript
 // src/module.ts
-import { defineModule } from "@izumisy-tailor/omakase-modules/builder";
+import {
+  defineModule,
+  type TablesFromNames,
+} from "@izumisy-tailor/omakase-modules/builder";
 import type { ModuleConfig } from "./types";
-import type { MyModuleTables } from "./tailordb/context";
+import { tableNames } from "./tailordb";
 import * as pkg from "../package.json";
 
-export default defineModule<ModuleConfig, MyModuleTables>({
+export default defineModule<ModuleConfig, TablesFromNames<typeof tableNames>>({
   packageName: pkg.name,
 });
 ```
 
-The `packageName` must match the `name` field in your `package.json`.
+The `packageName` must match the `name` field in your `package.json`. The `TablesFromNames` utility type derives the table types from `tableNames`, ensuring they stay in sync.
 
 ## 2. Define Configuration Types
 
@@ -62,55 +64,48 @@ export type ModuleConfig = {
 };
 ```
 
-## 3. Define Table Types
-
-Create type definitions for your module's tables:
-
-```typescript
-// src/tailordb/context.ts
-import type { TailorDBType } from "@tailor-platform/sdk";
-import type { ModuleConfig } from "../types";
-
-export type MyModuleTables = {
-  product: TailorDBType;
-  category: TailorDBType;
-};
-
-export type ModuleFactoryContext = {
-  config: ModuleConfig;
-};
-```
-
-## 4. Build Tables with Configuration
+## 3. Build Tables with Configuration
 
 Use `withModuleConfiguration` to access configuration when building tables:
 
 ```typescript
 // src/tailordb/index.ts
-import { withModuleConfiguration } from "@izumisy-tailor/omakase-modules/builder";
-import type { MyModuleTables } from "./context";
+import {
+  withModuleConfiguration,
+  type TablesFromNames,
+} from "@izumisy-tailor/omakase-modules/builder";
 import moduleDef from "../module";
 import { buildProductTable } from "./product";
 import { buildCategoryTable } from "./category";
 
-const tables = await withModuleConfiguration(moduleDef, (context) => {
+/**
+ * List of table names exported by this module.
+ * This is the single source of truth for table definitions.
+ */
+export const tableNames = ["product", "category"] as const;
+
+/**
+ * Factory function that creates tailordb tables with the given module configuration.
+ * This is called by the wrapper files generated by getModulesReference.
+ */
+export default withModuleConfiguration(moduleDef, (context) => {
   const category = buildCategoryTable(context);
   const product = buildProductTable(context, { category });
 
-  return { product, category } satisfies MyModuleTables;
+  return { product, category } satisfies TablesFromNames<typeof tableNames>;
 });
-
-export const productTable = tables.product;
-export const categoryTable = tables.category;
 ```
 
+> **Important**: The `tableNames` export is required for the wrapper generator to create named exports for each table.
+
 ```typescript
 // src/tailordb/product.ts
-import { db } from "@tailor-platform/sdk";
-import type { ModuleFactoryContext } from "./context";
+import { type ModuleFactoryContext } from "@izumisy-tailor/omakase-modules/builder";
+import { db, type TailorDBType } from "@tailor-platform/sdk";
+import type { ModuleConfig } from "../types";
 
 export const buildProductTable = (
-  { config }: ModuleFactoryContext,
+  { config }: ModuleFactoryContext<ModuleConfig>,
   deps: { category: TailorDBType }
 ) => {
   const customAttributes = config.dataModel?.product?.customAttributes || {};
@@ -130,7 +125,7 @@ export const buildProductTable = (
 };
 ```
 
-## 5. Declare Dependencies on Other Modules
+## 4. Declare Dependencies on Other Modules
 
 If your module depends on other modules, use `ModuleDependency`:
 
@@ -149,26 +144,81 @@ export type ModuleConfig = {
 
 This ensures type-safe dependency injection when users configure your module.
 
+### Using Dependency Tables in TailorDB
+
+When your module needs to reference tables from dependency modules, use `loadedModules.getTables()` in an async factory function:
+
+```typescript
+// src/tailordb/index.ts
+import { withModuleConfiguration } from "@izumisy-tailor/omakase-modules/builder";
+import moduleDef from "../module";
+import commerceModuleTables from "omakase-module-commerce-core/backend/tailordb";
+
+export default withModuleConfiguration(
+  moduleDef,
+  async (context, loadedModules) => {
+    // Get tables from dependency modules
+    const { product, productVariant } = await loadedModules.getTables(
+      commerceModuleTables
+    );
+
+    const inventory = buildInventoryTable(context, { product, productVariant });
+    // ...
+  }
+);
+```
+
+### Using Dependency Tables in Executors
+
+Executors can also access dependency tables:
+
+```typescript
+// src/executors/myExecutor.ts
+import { withModuleConfiguration } from "@izumisy-tailor/omakase-modules/builder";
+import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
+import commerceModuleTables from "omakase-module-commerce-core/backend/tailordb";
+import moduleDef from "../module";
+
+export default withModuleConfiguration(
+  moduleDef,
+  async (_context, loadedModules) => {
+    const { productVariant } = await loadedModules.getTables(
+      commerceModuleTables
+    );
+
+    return createExecutor({
+      name: "my-executor",
+      trigger: recordCreatedTrigger({ type: productVariant }),
+      operation: { /* ... */ },
+    });
+  }
+);
+```
+
 ## File Export Requirements
 
 Due to Tailor SDK API requirements, **TailorDB** and **Resolvers/Executors** have different export patterns:
 
-**TailorDB**: Should use a single `index.ts` barrel export. All table definitions should be exported from one file. This is **strongly recommended** because it allows you to use `satisfies` to verify that all required tables are defined for the module:
+**TailorDB**: Should use a single `index.ts` barrel export with a `tableNames` constant and a default factory function. This is **strongly recommended** because:
+1. It allows you to use `satisfies` to verify that all required tables are defined
+2. The `tableNames` export enables the wrapper generator to create named exports
 
 ```typescript
 // src/tailordb/index.ts
-const tables = await withModuleConfiguration(moduleDef, (context) => {
+export const tableNames = ["product", "category"] as const;
+
+export default withModuleConfiguration(moduleDef, (context) => {
   const category = buildCategoryTable(context);
   const product = buildProductTable(context, { category });
 
   // Type error if any required table is missing
-  return { product, category } satisfies MyModuleTables;
+  return { product, category } satisfies TablesFromNames<typeof tableNames>;
 });
 ```
 
 ```
 src/tailordb/
-  index.ts          # Exports all tables
+  index.ts          # Exports tableNames and default factory
   product.ts        # Table builder (not directly exported)
   category.ts       # Table builder (not directly exported)
 ```
@@ -186,9 +236,9 @@ src/executors/
 
 This is because the Tailor SDK processes resolver and executor files individually, expecting each file to contain a single definition with a default export.
 
-## 6. Configure Package Exports
+## 5. Configure Package Exports
 
-Set up your `package.json` to export the built files.
+Set up your `package.json` to export the module files.
 
 > **Important**: The export paths `./backend/tailordb`, `./backend/resolvers/*`, and `./backend/executors/*` are **required** and must not be changed. The module system expects these exact paths to locate module files.
 
@@ -197,27 +247,17 @@ Set up your `package.json` to export the built files.
   "name": "my-module",
   "type": "module",
   "exports": {
-    ".": {
-      "default": "./dist/module.mjs",
-      "types": "./dist/module.d.mts"
-    },
-    "./backend/tailordb": {
-      "default": "./dist/tailordb/index.mjs",
-      "types": "./dist/tailordb/index.d.mts"
-    },
-    "./backend/resolvers/*": {
-      "default": "./dist/resolvers/*.mjs",
-      "types": "./dist/resolvers/*.d.mts"
-    },
-    "./backend/executors/*": {
-      "default": "./dist/executors/*.mjs",
-      "types": "./dist/executors/*.d.mts"
-    }
+    ".": "./src/module.ts",
+    "./backend/tailordb": "./src/tailordb/index.ts",
+    "./backend/resolvers/*": "./src/resolvers/*.ts",
+    "./backend/executors/*": "./src/executors/*.ts"
   }
 }
 ```
 
-Note that TailorDB uses an `index.mjs` barrel export, while resolvers and executors use wildcard patterns to export individual files.
+Note that TailorDB uses an `index.ts` barrel export, while resolvers and executors use wildcard patterns to export individual files.
+
+> **Design Note**: Modules always export TypeScript source files directly—there is no need to build or bundle them. The Tailor SDK handles TypeScript compilation and bundling as part of its deployment process, so providing raw `.ts` files eliminates unnecessary build steps and keeps the module development workflow simple.
 
 ## Best Practices
 
@@ -227,10 +267,10 @@ Always use factory functions (like `buildProductTable`) instead of directly expo
 
 ### Type Your Tables
 
-Use `satisfies` to ensure your returned tables match the expected type:
+Use `satisfies` with `TablesFromNames` to ensure your returned tables match the expected type:
 
 ```typescript
-return { product, category } satisfies MyModuleTables;
+return { product, category } satisfies TablesFromNames<typeof tableNames>;
 ```
 
 ### Provide Sensible Defaults
@@ -241,15 +281,15 @@ Always provide default values for optional configuration:
 const prefix = config.dataModel?.product?.docNumberPrefix ?? "PROD";
 ```
 
-### Export Table References
-
-Export individual table references for use in other modules:
+## Utility Types Reference
 
-```typescript
-export const productTable = tables.product;
-```
+The `@izumisy-tailor/omakase-modules/builder` package provides these utility types:
 
-This allows other modules to reference your tables in relations and executors.
+| Type | Description |
+|------|-------------|
+| `TablesFromNames<T>` | Derives a tables type from a `tableNames` array. `T` should be `typeof tableNames`. |
+| `ModuleFactoryContext<C>` | Context passed to table builder functions. `C` is your module's config type. |
+| `ModuleDependency<T>` | Type for declaring dependencies on other modules. `T` is the module's default export type. |
 
 ## Next Steps
 

package/docs/tutorials/using-modules.md

@@ -39,21 +39,25 @@ export default loadModules((loader) => {
 
 Each module exposes a `configure()` method that accepts a type-safe configuration object. The available options are defined by the module author.
 
-## 2. Set Up tsconfig.json
+> **Note**: The `loadModules` function registers all configured modules in a global registry, which is later used by `getModulesReference` to generate wrapper files.
 
-Configure path aliases in `tsconfig.json` to enable module configuration loading:
+## 2. Configure TypeScript Path Alias
 
-```json
+You must configure a path alias in your `tsconfig.json` to point to the `modules.ts` file you created above. This alias is required for the generated wrapper files to correctly import your module configuration:
+
+```jsonc
+// tsconfig.json
 {
   "compilerOptions": {
+    // ... other options
     "paths": {
-      "@izumisy-tailor/omakase-modules/config/loader": ["./modules.ts"]
+      "@omakase-modules/config": ["./modules"]
     }
   }
 }
 ```
 
-This tells the module system where to find your configuration file.
+The `@omakase-modules/config` alias should point to your `modules.ts` file (without the `.ts` extension). The wrapper files generated by `getModulesReference` use this alias to import the configured modules.
 
 ## 3. Reference Modules in tailor.config.ts
 
@@ -65,7 +69,7 @@ import { defineConfig } from "@tailor-platform/sdk";
 import { getModulesReference } from "@izumisy-tailor/omakase-modules/config/sdk";
 import modules from "./modules";
 
-const moduleReference = getModulesReference(modules);
+const moduleReference = await getModulesReference(modules);
 
 export default defineConfig({
   name: "my-app",
@@ -85,6 +89,15 @@ export default defineConfig({
 });
 ```
 
+`getModulesReference` generates wrapper files in `.tailor-sdk/.omakase` that properly inject module configurations and create named exports for each table. Make sure to add this directory to your `.gitignore`.
+
+### Generated Wrapper Files
+
+The wrapper generator creates files that:
+1. Import the factory function from each module
+2. Call it with the loaded modules from your `modules.ts`
+3. Export the results (tables, resolvers, executors) for use by Tailor SDK
+
 ## 4. Handle Module Dependencies
 
 When modules depend on other modules, you need to wire them together:
@@ -92,6 +105,7 @@ When modules depend on other modules, you need to wire them together:
 ```typescript
 // modules.ts
 import { loadModules } from "@izumisy-tailor/omakase-modules";
+import { db } from "@tailor-platform/sdk";
 import ecommerceCoreModule from "omakase-module-commerce-core";
 import orderModule from "omakase-module-order";
 import inventoryModule from "omakase-module-inventory";
@@ -100,7 +114,16 @@ export default loadModules((loader) => {
   // Add the base module first
   const $commerce = loader.add(
     ecommerceCoreModule.configure({
-      config: { /* ... */ },
+      config: {
+        dataModel: {
+          product: {
+            docNumberPrefix: "PP-PROD",
+            customAttributes: {
+              customStatus: db.enum(["new", "used", "refurbished"]),
+            },
+          },
+        },
+      },
     })
   );
 
@@ -132,7 +155,7 @@ export default loadModules((loader) => {
 });
 ```
 
-The `loader.add()` method returns the configured module, which can then be passed as a dependency to other modules.
+The `loader.add()` method returns the configured module, which can then be passed as a dependency to other modules. This ensures type-safe dependency wiring.
 
 ## Common Configuration Options
 
@@ -169,6 +192,33 @@ config: {
 }
 ```
 
+### Module-Specific Options
+
+Some modules have their own configuration options:
+
+```typescript
+// Inventory module example
+config: {
+  dbNamespace: "main",  // Required: TailorDB namespace for this module
+  invantoryBootstrapBaseValue: 200,  // Module-specific option
+  dependencies: { /* ... */ },
+}
+```
+
+## Troubleshooting
+
+### Module Not Found
+
+If you see errors about modules not being found, ensure:
+1. The module is installed as a dependency in your `package.json`
+2. The module is added via `loader.add()` in your `modules.ts`
+
+### Type Errors with Dependencies
+
+If you see type errors when passing dependencies:
+1. Ensure the dependency module is added before the dependent module
+2. Use the return value from `loader.add()` as the dependency value
+
 ## Next Steps
 
 - See [Creating Modules](./creating-modules.md) if you want to build your own reusable modules

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@izumisy-tailor/omakase-modules",
   "private": false,
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Modularization mechanism for Tailor Platform application powered by Tailor SDK",
   "type": "module",
   "files": [
@@ -9,18 +9,9 @@
     "docs"
   ],
   "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,17 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "tsdown": "^0.18.0",
-    "typescript": "^5"
+    "typescript": "^5",
+    "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"
   }
 }

package/src/builder/helpers.ts

@@ -1,3 +1,5 @@
+import type { TailorDBType } from "@tailor-platform/sdk";
+
 type ModuleBuilderProps<C extends Record<string, unknown>> = {
   config: C;
 };
@@ -49,3 +51,41 @@ export type ModuleDependency<T extends DefinedModule<any, any>> =
         readonly __tablesBrand?: Tables;
       }
     : never;
+
+// ============================================================================
+// 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

@@ -3,5 +3,7 @@ export {
   type ConfiguredModule,
   type DefinedModule,
   type ModuleDependency,
+  type TablesFromNames,
+  type ModuleFactoryContext,
 } from "./helpers";
 export { withModuleConfiguration } from "./register";

package/src/builder/register.ts

@@ -1,34 +1,50 @@
-import type { ModuleConfigLoaderReturn } from "../stub-loader/interface";
+import type { LoadedModules } from "../config/module-loader";
 import type { DefinedModule } from "./helpers";
 
-type ModuleFactoryContext<C extends Record<string, unknown>> = Awaited<
-  ModuleConfigLoaderReturn<C>
->;
+type ModuleFactoryContext<C extends Record<string, unknown>> = {
+  config: C;
+};
 
 /**
- * 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>,
   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);
+  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);
+  };
 };