@izumisy-tailor/omakase-modules 0.1.0 → 0.3.0

package/src/builder/helpers.ts

@@ -0,0 +1,91 @@
+import type { TailorDBType } from "@tailor-platform/sdk";
+
+type ModuleBuilderProps<C extends Record<string, unknown>> = {
+  config: C;
+};
+
+export type ConfiguredModule<
+  C extends Record<string, unknown> = Record<string, unknown>
+> = {
+  packageName: string;
+  moduleProps: ModuleBuilderProps<C>;
+};
+
+export type DefinedModule<
+  C extends Record<string, unknown>,
+  Tables extends Record<string, unknown> = Record<string, unknown>
+> = {
+  packageName: string;
+  configure: (props: ModuleBuilderProps<C>) => ConfiguredModule<C>;
+  /**
+   * @internal Type-only hook so that table shapes flow through helper utilities.
+   */
+  readonly __tablesBrand?: Tables;
+};
+
+export const defineModule = <
+  C extends Record<string, unknown>,
+  Tables extends Record<string, unknown> = Record<string, unknown>
+>(baseProps: {
+  /**
+   * The package name of the module.
+   *
+   * This is required to be the same as the name field in package.json
+   */
+  packageName: string;
+}): DefinedModule<C, Tables> => {
+  return {
+    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;
+
+// ============================================================================
+// 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

@@ -0,0 +1,9 @@
+export {
+  defineModule,
+  type ConfiguredModule,
+  type DefinedModule,
+  type ModuleDependency,
+  type TablesFromNames,
+  type ModuleFactoryContext,
+} from "./helpers";
+export { withModuleConfiguration } from "./register";

package/src/builder/register.ts

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

package/src/config/index.ts

@@ -0,0 +1 @@
+export { loadModules, ModuleLoader, type LoadedModules } from "./module-loader";

package/src/config/module-loader.ts

@@ -0,0 +1,93 @@
+import { ConfiguredModule } from "../builder/helpers";
+
+/**
+ * Module loader
+ * Builder for registering modules within loadModules
+ */
+export class ModuleLoader {
+  private modules: Array<ConfiguredModule<any>> = [];
+
+  /**
+   * Add a module to the loader
+   * @param module Configured module
+   * @returns The added module (can be used as a dependency for other modules)
+   */
+  add<C extends Record<string, unknown>>(
+    module: ConfiguredModule<C>
+  ): ConfiguredModule<C> {
+    this.modules.push(module);
+    return module;
+  }
+
+  /**
+   * Get all registered modules
+   * @internal
+   */
+  _getModules(): Array<ConfiguredModule<any>> {
+    return this.modules;
+  }
+}
+
+export type LoadedModules = {
+  loadedModules: Record<string, ConfiguredModule<any>>;
+  loadConfig: <C extends Record<string, unknown>>(module: {
+    packageName: string;
+  }) => {
+    config: C;
+  };
+  /**
+   * Get the tables from a dependency module by calling its factory function.
+   * This is used when an executor or resolver needs to reference tables from another module.
+   *
+   * @param factory The factory function exported by the dependency module's tailordb/index.ts
+   * @returns The tables created by the factory
+   */
+  getTables: <T>(
+    factory: (loadedModules: LoadedModules) => Promise<T>
+  ) => Promise<T>;
+};
+
+/**
+ * Load modules with configuration
+ * @param configurator Function that receives a loader, registers modules, and returns the loader
+ * @returns Loaded modules and loadConfig function
+ */
+export const loadModules = (
+  configurator: (loader: ModuleLoader) => ModuleLoader
+): LoadedModules => {
+  const emptyLoader = new ModuleLoader();
+  const modules = configurator(emptyLoader)._getModules();
+
+  const loadedModules = modules.reduce<Record<string, ConfiguredModule<any>>>(
+    (acc, module) => {
+      acc[module.packageName] = module;
+      return acc;
+    },
+    {}
+  );
+
+  const loadedModulesResult: LoadedModules = {
+    loadedModules,
+    loadConfig: <C extends Record<string, unknown>>(module: {
+      packageName: string;
+    }) => {
+      const loadedModule = loadedModules[module.packageName];
+      if (!loadedModule) {
+        throw new Error(
+          `Module "${module.packageName}" has not been configured. Ensure it is added via loadModules.`
+        );
+      }
+
+      return {
+        config: loadedModule.moduleProps.config as C,
+      };
+    },
+    getTables: async <T>(
+      factory: (loadedModules: LoadedModules) => Promise<T>
+    ): Promise<T> => {
+      return factory(loadedModulesResult);
+    },
+  };
+
+  return loadedModulesResult;
+};

package/src/config/sdk/index.ts

@@ -0,0 +1 @@
+export { getModulesReference } from "./paths";

package/src/config/sdk/paths.ts

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { LoadedModules } from "../module-loader";
+import { generateWrapperFiles, OMAKASE_WRAPPER_DIR } from "./wrapper/generator";
+
+export type GetModulesReferenceOptions = {
+  /**
+   * Base path for the application (defaults to process.cwd())
+   */
+  basePath?: string;
+  /**
+   * Whether to suppress log output (defaults to false)
+   */
+  silent?: boolean;
+};
+
+export const getModulesReference = async (
+  loadedModules: LoadedModules,
+  options: GetModulesReferenceOptions = {}
+) => {
+  const { basePath = process.cwd(), silent = false } = options;
+
+  // Log loaded modules information
+  const modulePackageNames = Object.keys(loadedModules.loadedModules);
+  if (!silent) {
+    console.log(`[omakase] Loaded ${modulePackageNames.length} module(s):\n`);
+    for (const name of modulePackageNames) {
+      console.log(` * ${name}`);
+    }
+    console.log("");
+  }
+
+  // Generate wrapper files and return paths to them
+  const wrapperPaths = await generateWrapperFiles(loadedModules, basePath);
+
+  return {
+    tailordb:
+      wrapperPaths.tailordb.length > 0
+        ? [path.join(OMAKASE_WRAPPER_DIR, "*", "tailordb", "*.ts")]
+        : [],
+    resolver:
+      wrapperPaths.resolver.length > 0
+        ? [path.join(OMAKASE_WRAPPER_DIR, "*", "resolvers", "*.ts")]
+        : [],
+    executor:
+      wrapperPaths.executor.length > 0
+        ? [path.join(OMAKASE_WRAPPER_DIR, "*", "executors", "*.ts")]
+        : [],
+  };
+};

package/src/config/sdk/wrapper/base.ts

@@ -0,0 +1,141 @@
+import dedent from "dedent";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Path alias for importing modules config.
+ * App's tsconfig.json should have: "@omakase-modules/config": ["./modules"]
+ */
+export const MODULES_IMPORT_PATH = "@omakase-modules/config";
+
+/**
+ * Category types for wrapper generation
+ */
+export type Category = "tailordb" | "resolvers" | "executors";
+
+/**
+ * Abstract base class for category-specific wrapper generation
+ */
+export abstract class WrapperStrategy {
+  constructor(
+    protected readonly packageName: string,
+    protected readonly basePath: string
+  ) {}
+
+  /**
+   * The category this strategy handles
+   */
+  abstract readonly category: Category;
+
+  /**
+   * Filter files to process for this category
+   */
+  abstract filterFiles(files: string[]): string[];
+
+  /**
+   * Get the module export path
+   */
+  abstract getExportPath(fileName: string): string;
+
+  /**
+   * Generate the export statements using the factory result.
+   * Default implementation exports the result as default export.
+   */
+  protected generateExports(): Promise<string> {
+    return Promise.resolve("export default result;");
+  }
+
+  /**
+   * Generate wrapper file content using template method
+   *
+   * The common header, imports, and factory call are included here.
+   */
+  async generateContent(moduleExportPath: string): Promise<string> {
+    const exports = await this.generateExports();
+
+    return dedent`
+      /**
+       * Auto-generated wrapper file by @izumisy-tailor/omakase-modules
+       * DO NOT EDIT THIS FILE MANUALLY
+       *
+       * This file calls the module's factory function with the app's loadModules result,
+       * ensuring proper configuration injection and avoiding tree-shaking issues.
+       */
+
+      // Import the loadModules result from the app's modules.ts
+      import modules from "${MODULES_IMPORT_PATH}";
+
+      // Import the factory function from the module
+      import createFactory from "${moduleExportPath}";
+
+      // Call the factory with loadModules result
+      const result = await createFactory(modules);
+
+      ${exports}
+    `;
+  }
+
+  /**
+   * Generate wrapper files for this category
+   */
+  async generateFiles(wrapperDir: string): Promise<string[]> {
+    const sourcePath = path.join(
+      this.basePath,
+      "node_modules",
+      this.packageName,
+      "src",
+      this.category
+    );
+
+    // Check if the source directory exists
+    if (!(await this.exists(sourcePath))) {
+      return [];
+    }
+
+    const allFiles = await fs.readdir(sourcePath);
+    const files = this.filterFiles(allFiles);
+    const wrapperPaths: string[] = [];
+
+    for (const file of files) {
+      const wrapperPath = await this.generateFile(wrapperDir, file);
+      wrapperPaths.push(wrapperPath);
+    }
+
+    return wrapperPaths;
+  }
+
+  /**
+   * Generate a single wrapper file for this category
+   */
+  private async generateFile(
+    wrapperDir: string,
+    fileName: string
+  ): Promise<string> {
+    const categoryWrapperDir = path.join(
+      wrapperDir,
+      this.packageName,
+      this.category
+    );
+    await fs.mkdir(categoryWrapperDir, { recursive: true });
+
+    const wrapperFilePath = path.join(categoryWrapperDir, fileName);
+    const moduleExportPath = this.getExportPath(fileName);
+    const content = await this.generateContent(moduleExportPath);
+
+    await fs.writeFile(wrapperFilePath, content, "utf-8");
+
+    return wrapperFilePath;
+  }
+
+  /**
+   * Check if a path exists
+   */
+  private async exists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/config/sdk/wrapper/generator.ts

@@ -0,0 +1,52 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { LoadedModules } from "../../module-loader";
+import { createStrategy } from "./strategies";
+
+/**
+ * Directory where wrapper files are generated
+ */
+export const OMAKASE_WRAPPER_DIR = ".tailor-sdk/.omakase";
+
+/**
+ * Generates wrapper files for each module's tailordb, executor, and resolver files.
+ * These wrappers import the factory functions from modules and call them with
+ * the loadModules result from the app's modules.ts.
+ */
+export const generateWrapperFiles = async (
+  loadedModules: LoadedModules,
+  basePath: string = process.cwd()
+) => {
+  const wrapperDir = path.join(basePath, OMAKASE_WRAPPER_DIR);
+  const modulePackageNames = Object.keys(loadedModules.loadedModules);
+
+  // Clean up existing wrapper directory
+  try {
+    await fs.access(wrapperDir);
+    await fs.rm(wrapperDir, { recursive: true });
+  } catch {
+    // Directory doesn't exist, no need to clean up
+  }
+
+  const result = {
+    tailordb: [] as string[],
+    resolver: [] as string[],
+    executor: [] as string[],
+  };
+
+  for (const packageName of modulePackageNames) {
+    const strategyFor = createStrategy(packageName, basePath);
+
+    result.tailordb.push(
+      ...(await strategyFor("tailordb").generateFiles(wrapperDir))
+    );
+    result.resolver.push(
+      ...(await strategyFor("resolvers").generateFiles(wrapperDir))
+    );
+    result.executor.push(
+      ...(await strategyFor("executors").generateFiles(wrapperDir))
+    );
+  }
+
+  return result;
+};

package/src/config/sdk/wrapper/strategies.ts

@@ -0,0 +1,102 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { Category, WrapperStrategy } from "./base";
+
+/**
+ * Strategy for tailordb category
+ */
+class TailorDBStrategy extends WrapperStrategy {
+  readonly category = "tailordb" as const;
+  filterFiles(files: string[]) {
+    return files.filter((file) => file === "index.ts");
+  }
+
+  getExportPath() {
+    return `${this.packageName}/backend/tailordb`;
+  }
+
+  protected async generateExports() {
+    const tableNames = await this.importTableNames();
+    return tableNames
+      .map((name) => `export const ${name}Table = result.${name};`)
+      .join("\n");
+  }
+
+  /**
+   * Import tableNames from a module's tailordb/index.ts using dynamic import.
+   * Uses createRequire to leverage Node.js module resolution from the app's context.
+   */
+  private async importTableNames(): Promise<readonly string[]> {
+    try {
+      const appRequire = createRequire(
+        path.join(this.basePath, "package.json")
+      );
+      const modulePath = appRequire.resolve(
+        `${this.packageName}/backend/tailordb`
+      );
+      const module = await import(`file://${modulePath}`);
+      if (!module.tableNames) {
+        console.warn(
+          `[warn] tableNames not found in ${this.packageName}/backend/tailordb. Expected: export const tableNames = [...] as const;`
+        );
+        return [];
+      }
+      return module.tableNames;
+    } catch (error) {
+      console.warn(
+        `[warn] Failed to import ${this.packageName}/backend/tailordb:`,
+        error
+      );
+      return [];
+    }
+  }
+}
+
+/**
+ * Strategy for resolvers category
+ */
+class ResolversStrategy extends WrapperStrategy {
+  readonly category = "resolvers" as const;
+
+  filterFiles(files: string[]) {
+    return files.filter((file) => file.endsWith(".ts") && file !== "index.ts");
+  }
+
+  getExportPath(fileName: string) {
+    const baseName = fileName.replace(/\.ts$/, "");
+    return `${this.packageName}/backend/resolvers/${baseName}`;
+  }
+}
+
+/**
+ * Strategy for executors category
+ */
+class ExecutorsStrategy extends WrapperStrategy {
+  readonly category = "executors" as const;
+
+  filterFiles(files: string[]) {
+    return files.filter((file) => file.endsWith(".ts") && file !== "index.ts");
+  }
+
+  getExportPath(fileName: string) {
+    const baseName = fileName.replace(/\.ts$/, "");
+    return `${this.packageName}/backend/executors/${baseName}`;
+  }
+}
+
+/**
+ * Factory to create strategy instance for each category.
+ * Returns a function that takes a category and returns a strategy.
+ */
+export const createStrategy =
+  (packageName: string, basePath: string) =>
+  (category: Category): WrapperStrategy => {
+    switch (category) {
+      case "tailordb":
+        return new TailorDBStrategy(packageName, basePath);
+      case "resolvers":
+        return new ResolversStrategy(packageName, basePath);
+      case "executors":
+        return new ExecutorsStrategy(packageName, basePath);
+    }
+  };

package/dist/builder/index.d.mts

@@ -1,3 +0,0 @@
-import { i as defineModule, n as DefinedModule, r as ModuleDependency, t as ConfiguredModule } from "../helpers-CNjRbrYN.mjs";
-import { t as withModuleConfiguration } from "../index-BoAL29Di.mjs";
-export { ConfiguredModule, DefinedModule, ModuleDependency, defineModule, withModuleConfiguration };

package/dist/builder/index.mjs

@@ -1,35 +0,0 @@
-//#region src/builder/helpers.ts
-const defineModule = (baseProps) => {
-	return {
-		packageName: baseProps.packageName,
-		configure: (props) => {
-			return {
-				packageName: baseProps.packageName,
-				moduleProps: props
-			};
-		}
-	};
-};
-
-//#endregion
-//#region src/builder/register.ts
-/**
-* Load a module's configuration, define something.
-*
-* THis is a low-level utility composed by a specific builder function.
-*/
-const withModuleConfiguration = async (module, factory) => {
-	/**
-	* 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");
-	return await factory(await configLoader.loadConfig(module));
-};
-
-//#endregion
-export { defineModule, withModuleConfiguration };

package/dist/config/index.d.mts

@@ -1,2 +0,0 @@
-import { n as ModuleLoader, r as loadModules, t as LoadedModules } from "../module-loader-B4sA1i0A.mjs";
-export { type LoadedModules, ModuleLoader, loadModules };