@izumisy-tailor/omakase-modules 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,47 @@
+# 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](./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`

package/docs/tutorials/creating-modules.md

@@ -0,0 +1,296 @@
+# 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
+```
+
+## 1. Define the Module
+
+Create the module definition with `defineModule`:
+
+```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,
+});
+```
+
+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
+
+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 `ModuleDependency`:
+
+```typescript
+// src/types.ts
+import type { ModuleDependency } from "@izumisy-tailor/omakase-modules/builder";
+import type commerceCoreModule from "omakase-module-commerce-core";
+
+export type ModuleConfig = {
+  dataModel?: { /* ... */ };
+  dependencies: {
+    commerce: ModuleDependency<typeof commerceCoreModule>;
+  };
+};
+```
+
+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 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. 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",
+    "./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. |
+| `ModuleDependency<T>` | Type for declaring dependencies on other modules. `T` is the module's default export type. |
+
+## Next Steps
+
+- See [Using Modules](./using-modules.md) for how applications consume your module

package/docs/tutorials/using-modules.md

@@ -0,0 +1,224 @@
+# Using Modules in Your Application
+
+This guide explains how to use pre-built Omakase Modules in your Tailor Platform application.
+
+## Prerequisites
+
+- A Tailor Platform application
+- Modules installed as dependencies (e.g., `omakase-module-commerce-core`)
+
+## 1. Configure Modules
+
+Use `loadModules` to configure the modules your application needs:
+
+```typescript
+// modules.ts
+import { loadModules } from "@izumisy-tailor/omakase-modules";
+import { db } from "@tailor-platform/sdk";
+import ecommerceCoreModule from "omakase-module-commerce-core";
+
+export default loadModules((loader) => {
+  loader.add(
+    ecommerceCoreModule.configure({
+      config: {
+        dataModel: {
+          product: {
+            docNumberPrefix: "MY-PROD",
+            customAttributes: {
+              customStatus: db.enum(["new", "used", "refurbished"]),
+            },
+          },
+        },
+      },
+    })
+  );
+
+  return loader;
+});
+```
+
+Each module exposes a `configure()` method that accepts a type-safe configuration object. The available options are defined by the module author.
+
+> **Note**: The `loadModules` function registers all configured modules in a global registry, which is later used by `getModulesReference` to generate wrapper files.
+
+## 2. Configure TypeScript Path Alias
+
+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": {
+      "@omakase-modules/config": ["./modules"]
+    }
+  }
+}
+```
+
+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
+
+Use `getModulesReference` to include module files in your Tailor configuration:
+
+```typescript
+// tailor.config.ts
+import { defineConfig } from "@tailor-platform/sdk";
+import { getModulesReference } from "@izumisy-tailor/omakase-modules/config/sdk";
+import modules from "./modules";
+
+const moduleReference = await getModulesReference(modules);
+
+export default defineConfig({
+  name: "my-app",
+  db: {
+    main: {
+      files: ["./src/tailordb/*.ts", ...moduleReference.tailordb],
+    },
+  },
+  resolver: {
+    "main-pipeline": {
+      files: ["./src/resolvers/*.ts", ...moduleReference.resolver],
+    },
+  },
+  executor: {
+    files: ["./src/executors/**/*.ts", ...moduleReference.executor],
+  },
+});
+```
+
+`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:
+
+```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(
+    ecommerceCoreModule.configure({
+      config: {
+        dataModel: {
+          product: {
+            docNumberPrefix: "PP-PROD",
+            customAttributes: {
+              customStatus: db.enum(["new", "used", "refurbished"]),
+            },
+          },
+        },
+      },
+    })
+  );
+
+  // Pass the commerce module as a dependency
+  const $order = loader.add(
+    orderModule.configure({
+      config: {
+        dependencies: {
+          commerce: $commerce,
+        },
+      },
+    })
+  );
+
+  // Inventory depends on both commerce and order
+  loader.add(
+    inventoryModule.configure({
+      config: {
+        dbNamespace: "main",
+        dependencies: {
+          commerce: $commerce,
+          order: $order,
+        },
+      },
+    })
+  );
+
+  return loader;
+});
+```
+
+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
+
+Most modules support these common configuration patterns:
+
+### Custom Attributes
+
+Add custom fields to module tables:
+
+```typescript
+config: {
+  dataModel: {
+    product: {
+      customAttributes: {
+        myCustomField: db.string(),
+        priority: db.int(),
+      },
+    },
+  },
+}
+```
+
+### Document Number Prefixes
+
+Customize document number prefixes:
+
+```typescript
+config: {
+  dataModel: {
+    order: {
+      docNumberPrefix: "ORD-2024",
+    },
+  },
+}
+```
+
+### 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,34 +1,17 @@
 {
   "name": "@izumisy-tailor/omakase-modules",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Modularization mechanism for Tailor Platform application powered by Tailor SDK",
   "type": "module",
   "files": [
-    "dist"
+    "src",
+    "docs"
   ],
   "exports": {
-    ".": {
-      "default": "./dist/config/index.mjs",
-      "types": "./dist/config/index.d.mts"
-    },
-    "./config/sdk": {
-      "default": "./dist/config/sdk/index.mjs",
-      "types": "./dist/config/sdk/index.d.mts"
-    },
-    "./builder": {
-      "default": "./dist/builder/index.mjs",
-      "types": "./dist/builder/index.d.mts"
-    },
-    "./config/loader": {
-      "default": "./dist/stub-loader/index.mjs",
-      "types": "./dist/stub-loader/index.d.mts"
-    }
-  },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "type-check": "tsc"
+    ".": "./src/config/index.ts",
+    "./config/sdk": "./src/config/sdk/index.ts",
+    "./builder": "./src/builder/index.ts"
   },
   "keywords": [
     "tailor-platform",
@@ -38,13 +21,19 @@
   ],
   "author": "Tailor Inc.",
   "license": "MIT",
-  "packageManager": "pnpm@10.22.0",
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "tsdown": "^0.18.0",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "^4.0.16"
   },
   "peerDependencies": {
-    "@tailor-platform/sdk": "^0.17.0"
+    "@tailor-platform/sdk": "^0.20.0"
+  },
+  "dependencies": {
+    "dedent": "^1.7.1"
+  },
+  "scripts": {
+    "type-check": "tsc",
+    "test": "vitest run"
   }
-}
+}