@izumisy-tailor/omakase-modules 0.2.0 → 0.4.0

package/README.md

@@ -29,31 +29,3 @@ pnpm add @izumisy-tailor/omakase-modules
 
 - [Using Modules](./docs/tutorials/using-modules.md) - How to use pre-built modules in your application
 - [Creating Modules](./docs/tutorials/creating-modules.md) - How to create reusable modules
-
-## API Reference
-
-### `@izumisy-tailor/omakase-modules`
-
-- `loadModules(configurator)` - Load and configure modules in your application
-
-### `@izumisy-tailor/omakase-modules/builder`
-
-- `defineModule<Config, Tables>(options)` - Define a new module
-- `withModuleConfiguration(module, factory)` - Access module configuration in TailorDB, Resolvers, and Executors
-- `ModuleDependency<T>` - Type utility for declaring module dependencies
-
-### `@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/generated/README.md

@@ -0,0 +1,35 @@
+**@izumisy-tailor/omakase-modules**
+
+***
+
+# Omakase Modules
+
+A **configurable module system** for Tailor Platform. Define reusable modules with type-safe configurations and share them across applications.
+
+## Motivation
+
+When building applications on Tailor Platform, you often face these challenges:
+
+1. **Reusability**: You want to reuse common data models and business logic (e.g., e-commerce, inventory, orders) across multiple applications
+2. **Customizability**: While modules should be reusable, you need to customize them for application-specific requirements
+3. **Dependency Management**: Module dependencies should be explicitly defined and managed in a type-safe manner
+
+Omakase Modules is designed to solve these challenges by providing a flexible, type-safe module system.
+
+## Key Features
+
+- **Module Definition**: Define modules with `defineModule` and declare type-safe configuration schemas
+- **Module Configuration**: Configure modules at the application level, injecting custom attributes and prefixes
+- **Dependency Management**: Explicitly define inter-module dependencies with the `ModuleDependency` type
+- **Configuration Injection**: Inject configurations into TailorDB, Resolvers, and Executors using `withModuleConfiguration`
+
+## Installation
+
+```bash
+pnpm add @izumisy-tailor/omakase-modules
+```
+
+## Documentation
+
+- [Using Modules](_media/using-modules.md) - How to use pre-built modules in your application
+- [Creating Modules](_media/creating-modules.md) - How to create reusable modules

package/docs/generated/_media/creating-modules.md

@@ -0,0 +1,471 @@
+# Creating Modules
+
+This guide explains how to create reusable Omakase Modules that can be shared across applications.
+
+## Module Structure
+
+A typical module package has this structure:
+
+```
+my-module/
+  package.json
+  tsconfig.json
+  src/
+    module.ts           # Module definition and table types export
+    types.ts            # Configuration types
+    tailordb/
+      index.ts          # TailorDB exports with tableNames
+      my-table.ts       # Table builders
+    resolvers/
+      my-resolver.ts
+    executors/
+      my-executor.ts
+```
+
+## Prerequisites: tsconfig.json Path Aliases
+
+Your module's `tsconfig.json` must include the following path aliases for the module system to function correctly:
+
+```jsonc
+{
+  "compilerOptions": {
+    "paths": {
+      "@omakase-modules/config": ["./src/module"],
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+| Alias | Path | Purpose |
+|-------|------|---------|
+| `@omakase-modules/config` | `["./src/module"]` | **Required**. Points to your module definition file. The wrapper generator uses this alias to import your module's configuration during code generation. |
+| `@/*` | `["./src/*"]` | **Required**. Provides a shorthand for importing from the `src/` directory. Used internally during development mode to resolve local source files. |
+
+## 1. Define the Module
+
+Create the module definition with `defineModule`. The module definition uses a builder pattern:
+
+```typescript
+// src/module.ts
+import {
+  defineModule,
+  type TablesFromNames,
+} from "@izumisy-tailor/omakase-modules/builder";
+import type { ModuleConfig } from "./types";
+import { tableNames } from "./tailordb";
+import * as pkg from "../package.json";
+
+export default defineModule<ModuleConfig, TablesFromNames<typeof tableNames>>({
+  packageName: pkg.name,
+})
+  .withDevConfig({})  // Optional: default config for development
+  .build();
+```
+
+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.
+
+### Builder Methods
+
+- `.withDevConfig(config)` - Sets the default configuration used during module development
+- `.withDependencies(deps)` - Declares dependencies on other modules (see section 4)
+- `.build()` - Finalizes the module definition (must be called at the end)
+
+## 2. Define Configuration Types
+
+Define what configuration options your module accepts:
+
+```typescript
+// src/types.ts
+import { TailorField } from "@tailor-platform/sdk";
+
+type DataModelConfiguration = {
+  docNumberPrefix?: string;
+  customAttributes?: Record<string, TailorField<any>>;
+};
+
+export type ModuleConfig = {
+  dataModel?: {
+    product?: DataModelConfiguration;
+    category?: DataModelConfiguration;
+  };
+};
+```
+
+## 3. Build Tables with Configuration
+
+Use `withModuleConfiguration` to access configuration when building tables:
+
+```typescript
+// src/tailordb/index.ts
+import {
+  withModuleConfiguration,
+  type TablesFromNames,
+} from "@izumisy-tailor/omakase-modules/builder";
+import moduleDef from "../module";
+import { buildProductTable } from "./product";
+import { buildCategoryTable } from "./category";
+
+/**
+ * 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 TablesFromNames<typeof tableNames>;
+});
+```
+
+> **Important**: The `tableNames` export is required for the wrapper generator to create named exports for each table.
+
+```typescript
+// src/tailordb/product.ts
+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<ModuleConfig>,
+  deps: { category: TailorDBType }
+) => {
+  const customAttributes = config.dataModel?.product?.customAttributes || {};
+  const docNumberPrefix = config.dataModel?.product?.docNumberPrefix ?? "PROD";
+
+  return db.type("Product", {
+    name: db.string(),
+    sku: db.string().unique(),
+    categoryId: db.uuid({ optional: true }).relation({
+      type: "keyOnly",
+      toward: { type: deps.category },
+    }),
+    docNumber: db.docNumber({ prefix: docNumberPrefix }),
+    ...customAttributes,
+    ...db.fields.timestamps(),
+  });
+};
+```
+
+## 4. Declare Dependencies on Other Modules
+
+If your module depends on other modules, use `.withDependencies()` in your module definition:
+
+```typescript
+// src/module.ts
+import {
+  defineModule,
+  type TablesFromNames,
+} from "@izumisy-tailor/omakase-modules/builder";
+import { ModuleConfig } from "./types";
+import { tableNames } from "./tailordb";
+import * as pkg from "../package.json";
+import commerceModule from "omakase-module-commerce-core";
+import orderModule from "omakase-module-order";
+
+export default defineModule<ModuleConfig, TablesFromNames<typeof tableNames>>({
+  packageName: pkg.name,
+})
+  .withDevConfig({
+    dbNamespace: "main-db",
+  })
+  .withDependencies({ commerce: commerceModule, order: orderModule })
+  .build();
+```
+
+The dependency modules are passed directly to `.withDependencies()`. 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,
+  type TablesFromNames,
+} from "@izumisy-tailor/omakase-modules/builder";
+import moduleDef from "../module";
+import { buildInventoryTable } from "./inventory";
+import { buildInventoryTransactionTable } from "./inventory-transaction";
+import { buildStockAdjustmentTable } from "./stock-adjustment";
+import commerceModuleTables from "omakase-module-commerce-core/backend/tailordb";
+import orderModuleTables from "omakase-module-order/backend/tailordb";
+
+export const tableNames = [
+  "inventory",
+  "inventoryTransaction",
+  "stockAdjustment",
+] as const;
+
+export default withModuleConfiguration(
+  moduleDef,
+  async (context, loadedModules) => {
+    // Get tables from dependency modules
+    const { product, productVariant } = await loadedModules.getTables(
+      commerceModuleTables
+    );
+    const { order } = await loadedModules.getTables(orderModuleTables);
+
+    const inventory = buildInventoryTable(context, { product, productVariant });
+    const inventoryTransaction = buildInventoryTransactionTable(context, {
+      inventory,
+      order,
+    });
+    const stockAdjustment = buildStockAdjustmentTable(context, {
+      inventory,
+    });
+
+    return {
+      inventory,
+      inventoryTransaction,
+      stockAdjustment,
+    } satisfies TablesFromNames<typeof tableNames>;
+  }
+);
+```
+
+### 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 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
+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 TablesFromNames<typeof tableNames>;
+});
+```
+
+```
+src/tailordb/
+  index.ts          # Exports tableNames and default factory
+  product.ts        # Table builder (not directly exported)
+  category.ts       # Table builder (not directly exported)
+```
+
+**Resolvers/Executors**: Must be exported as **separate files**. Each resolver or executor must be in its own file and cannot be barrel-exported from an `index.ts`:
+
+```
+src/resolvers/
+  getProduct.ts     # Each resolver in its own file
+  listProducts.ts
+src/executors/
+  onProductCreated.ts   # Each executor in its own file
+  onOrderPlaced.ts
+```
+
+This is because the Tailor SDK processes resolver and executor files individually, expecting each file to contain a single definition with a default export.
+
+## 5. Set Up tailor.config.ts for Module Development
+
+Every module needs a `tailor.config.ts` file for development. This file uses `loadModuleForDev` to resolve the module's factory functions into actual TailorDB table definitions, enabling the Tailor SDK's generator to produce Kysely type definitions.
+
+### Why tailor.config.ts is Required
+
+Omakase Modules use a factory pattern—tables are not defined directly but through `withModuleConfiguration` functions that receive configuration at runtime. The Tailor SDK's `@tailor-platform/kysely-type` generator needs concrete table definitions to generate TypeScript types.
+
+`loadModuleForDev` bridges this gap by:
+1. Resolving your module's factory functions with the `devConfig` you defined
+2. Automatically registering any dependency modules
+3. Producing actual TailorDB table definitions that the generator can process
+
+The generated Kysely types (`src/generated/tailordb.ts`) enable:
+- **Type-safe SQL queries** in your module's executors and resolvers
+- **Cross-module JOIN queries** when other modules depend on yours via the `getDB` function
+
+### Basic tailor.config.ts
+
+```typescript
+// tailor.config.ts
+import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
+import {
+  loadModuleForDev,
+  getModulesReference,
+} from "@izumisy-tailor/omakase-modules/config/sdk";
+import myModule from "./src/module";
+
+const moduleReference = await getModulesReference(
+  loadModuleForDev(myModule)
+);
+
+export default defineConfig({
+  name: "my-module",
+
+  db: {
+    "main-db": {
+      files: [...moduleReference.tailordb],
+    },
+  },
+});
+
+export const generators = defineGenerators([
+  "@tailor-platform/kysely-type",
+  { distPath: "./src/generated/tailordb.ts" },
+]);
+```
+
+> **Note**: Resolvers and executors are not required in `tailor.config.ts` during module development. The primary purpose is to generate Kysely type definitions for type-safe database queries.
+
+### The Role of devConfig
+
+The `devConfig` you define in your module with `.withDevConfig()` is the default configuration used by `loadModuleForDev`. This allows the generator to produce type definitions without explicitly passing configuration each time.
+
+If your module doesn't require any configuration, you can omit `.withDevConfig()` entirely—`loadModuleForDev` will use an empty object `{}` as the default.
+
+```typescript
+// src/module.ts - module with configuration
+export default defineModule<ModuleConfig, TablesFromNames<typeof tableNames>>({
+  packageName: pkg.name,
+})
+  .withDevConfig({
+    // Default configuration for development
+    dataModel: {
+      product: { docNumberPrefix: "DEV" },
+    },
+  })
+  .build();
+
+// src/module.ts - module without configuration (withDevConfig can be omitted)
+export default defineModule<ModuleConfig, TablesFromNames<typeof tableNames>>({
+  packageName: pkg.name,
+}).build();
+```
+
+When `loadModuleForDev(myModule)` is called without a second argument, it uses this `devConfig` (or `{}` if not defined). You can override it by passing a custom config:
+
+```typescript
+// Use custom config instead of devConfig
+loadModuleForDev(myModule, {
+  dataModel: {
+    product: { docNumberPrefix: "TEST" },
+  },
+});
+```
+
+This flexibility is useful for:
+- **Multiple tailor.config.ts files**: When you need different configurations for different environments (e.g., testing vs development)
+- **Temporary overrides**: When you want to test with a different configuration without modifying `devConfig`
+- **CI/CD pipelines**: When configuration needs to be passed dynamically from environment variables
+
+### Handling Dependencies in Development
+
+When your module has dependencies declared with `.withDependencies()`, `loadModuleForDev` automatically registers all dependency modules with empty configurations. This allows the generator to produce types that include dependency tables, enabling JOIN queries across module boundaries.
+
+```typescript
+// Module with dependencies
+export default defineModule<ModuleConfig, TablesFromNames<typeof tableNames>>({
+  packageName: pkg.name,
+})
+  .withDependencies({ commerce: commerceModule })
+  .withDevConfig({ /* ... */ })
+  .build();
+
+// In tailor.config.ts - dependencies are auto-registered
+const moduleReference = await getModulesReference(
+  loadModuleForDev(myModule)  // commerceModule is automatically loaded with {}
+);
+```
+
+> **Note**: In development context, dependency modules are registered with empty configurations (`{}`). Actual configuration for dependencies is provided when your module is used in an application via `loadModules`.
+
+## 6. Configure Package Exports
+
+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.
+
+```json
+{
+  "name": "my-module",
+  "type": "module",
+  "exports": {
+    ".": "./src/module.ts",
+    "./db": "./src/db.ts",
+    "./backend/tailordb": "./src/tailordb/index.ts",
+    "./backend/resolvers/*": "./src/resolvers/*.ts",
+    "./backend/executors/*": "./src/executors/*.ts"
+  }
+}
+```
+
+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
+
+### Use Factory Functions for Tables
+
+Always use factory functions (like `buildProductTable`) instead of directly exporting table definitions. This allows configuration to be injected.
+
+### Type Your Tables
+
+Use `satisfies` with `TablesFromNames` to ensure your returned tables match the expected type:
+
+```typescript
+return { product, category } satisfies TablesFromNames<typeof tableNames>;
+```
+
+### Provide Sensible Defaults
+
+Always provide default values for optional configuration:
+
+```typescript
+const prefix = config.dataModel?.product?.docNumberPrefix ?? "PROD";
+```
+
+## Utility Types Reference
+
+The `@izumisy-tailor/omakase-modules/builder` package provides these utility types:
+
+| 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. |
+
+## Next Steps
+
+- See [Using Modules](./using-modules.md) for how applications consume your module

package/docs/{tutorials → generated/_media}/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,33 +89,51 @@ 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:
+When modules depend on other modules, you need to wire them together. The `loader.add()` method returns the configured module, which can then be passed as a dependency to other modules via the `dependencies` property:
 
 ```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";
 
 export default loadModules((loader) => {
   // Add the base module first
-  const $commerce = loader.add(
+  const $ecommerceModule = loader.add(
     ecommerceCoreModule.configure({
-      config: { /* ... */ },
+      config: {
+        dataModel: {
+          product: {
+            docNumberPrefix: "PP-PROD",
+            customAttributes: {
+              customStatus: db.enum(["new", "used", "refurbished"]),
+            },
+          },
+        },
+      },
     })
   );
 
-  // Pass the commerce module as a dependency
-  const $order = loader.add(
+  // Pass the commerce module as a dependency via the dependencies property
+  const $orderModule = loader.add(
     orderModule.configure({
       config: {
-        dependencies: {
-          commerce: $commerce,
-        },
+        dataModel: {},
       },
+      dependencies: { commerce: $ecommerceModule },
     })
   );
 
@@ -119,12 +141,10 @@ export default loadModules((loader) => {
   loader.add(
     inventoryModule.configure({
       config: {
-        dbNamespace: "main",
-        dependencies: {
-          commerce: $commerce,
-          order: $order,
-        },
+        dbNamespace: "main-db",
+        invantoryBootstrapBaseValue: 300,
       },
+      dependencies: { commerce: $ecommerceModule, order: $orderModule },
     })
   );
 
@@ -132,7 +152,7 @@ export default loadModules((loader) => {
 });
 ```
 
-The `loader.add()` method returns the configured module, which can then be passed as a dependency to other modules.
+Note that dependencies are passed as a separate `dependencies` property alongside `config`, not nested inside `config`. This ensures type-safe dependency wiring.
 
 ## Common Configuration Options
 
@@ -169,6 +189,35 @@ config: {
 }
 ```
 
+### Module-Specific Options
+
+Some modules have their own configuration options:
+
+```typescript
+// Inventory module example
+inventoryModule.configure({
+  config: {
+    dbNamespace: "main",  // Required: TailorDB namespace for this module
+    invantoryBootstrapBaseValue: 200,  // Module-specific option
+  },
+  dependencies: { commerce: $ecommerceModule, order: $orderModule },
+})
+```
+
+## 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