@izumisy-tailor/omakase-modules 0.2.0 → 0.4.0

package/docs/tutorials/creating-modules.md

@@ -1,256 +0,0 @@
-# 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
-    types.ts            # Configuration types
-    tailordb/
-      index.ts          # TailorDB exports
-      context.ts        # Type definitions for tables
-      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 } from "@izumisy-tailor/omakase-modules/builder";
-import type { ModuleConfig } from "./types";
-import type { MyModuleTables } from "./tailordb/context";
-import * as pkg from "../package.json";
-
-export default defineModule<ModuleConfig, MyModuleTables>({
-  packageName: pkg.name,
-});
-```
-
-The `packageName` must match the `name` field in your `package.json`.
-
-## 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. 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
-
-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 moduleDef from "../module";
-import { buildProductTable } from "./product";
-import { buildCategoryTable } from "./category";
-
-const tables = await withModuleConfiguration(moduleDef, (context) => {
-  const category = buildCategoryTable(context);
-  const product = buildProductTable(context, { category });
-
-  return { product, category } satisfies MyModuleTables;
-});
-
-export const productTable = tables.product;
-export const categoryTable = tables.category;
-```
-
-```typescript
-// src/tailordb/product.ts
-import { db } from "@tailor-platform/sdk";
-import type { ModuleFactoryContext } from "./context";
-
-export const buildProductTable = (
-  { config }: ModuleFactoryContext,
-  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(),
-  });
-};
-```
-
-## 5. 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.
-
-## 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:
-
-```typescript
-// src/tailordb/index.ts
-const tables = await 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;
-});
-```
-
-```
-src/tailordb/
-  index.ts          # Exports all tables
-  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.
-
-## 6. Configure Package Exports
-
-Set up your `package.json` to export the built 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": {
-    ".": {
-      "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"
-    }
-  }
-}
-```
-
-Note that TailorDB uses an `index.mjs` barrel export, while resolvers and executors use wildcard patterns to export individual files.
-
-## 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` to ensure your returned tables match the expected type:
-
-```typescript
-return { product, category } satisfies MyModuleTables;
-```
-
-### Provide Sensible Defaults
-
-Always provide default values for optional configuration:
-
-```typescript
-const prefix = config.dataModel?.product?.docNumberPrefix ?? "PROD";
-```
-
-### Export Table References
-
-Export individual table references for use in other modules:
-
-```typescript
-export const productTable = tables.product;
-```
-
-This allows other modules to reference your tables in relations and executors.
-
-## Next Steps
-
-- See [Using Modules](./using-modules.md) for how applications consume your module

package/src/config/module-registry.ts

@@ -1,22 +0,0 @@
-import type { ConfiguredModule } from "../builder/helpers";
-
-const registry = new Map<string, ConfiguredModule<any>>();
-
-export const clearModuleRegistry = () => {
-  registry.clear();
-};
-
-export const registerConfiguredModules = (
-  modules: ReadonlyArray<ConfiguredModule<any>>
-) => {
-  modules.forEach((module) => {
-    registry.set(module.packageName, module);
-  });
-  return modules;
-};
-
-export const getConfiguredModule = <C extends Record<string, unknown>>(
-  packageName: string
-): ConfiguredModule<C> | undefined => {
-  return registry.get(packageName) as ConfiguredModule<C> | undefined;
-};

package/src/stub-loader/index.ts

@@ -1,3 +0,0 @@
-import { moduleConfigLoader } from "./interface";
-
-export default moduleConfigLoader;

package/src/stub-loader/interface.ts

@@ -1,40 +0,0 @@
-import { DefinedModule } from "../builder";
-
-export type ModuleConfigLoaderReturn<C extends Record<string, unknown>> =
-  Promise<{
-    config: C;
-  }>;
-
-const loadConfig = async <C extends Record<string, unknown>>(
-  _: DefinedModule<C, any>
-): ModuleConfigLoaderReturn<C> => {
-  console.warn(
-    `[warn] Empty module configuration loaded. Override "@izumisy-tailor/omakase-modules/config/loader" to "./modules.ts" in tsconfig.json paths in your app`
-  );
-
-  return {
-    config: {} as C,
-  };
-};
-
-/**
- * `moduleConfigLoader` is an interface for loading module configurations.
- *
- * By default, it throws an error indicating that the loader needs to be overridden in tsconfig.json.
- * Users should provide their "modules.ts" that calls `loadModules` which implements the actual loading logic.
- *
- * @example
- * ```
- * {
- *   "compilerOptions": {
- *     // ...
- *     "paths": {
- *       "@izumisy-tailor/omakase-modules/config/loader": ["./modules.ts"],
- *     }
- *   }
- * }
- * ```
- */
-export const moduleConfigLoader = {
-  loadConfig,
-};