@forinda/kickjs-multi-tenant 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Orinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { AppAdapter, AdapterMiddleware, Container } from '@forinda/kickjs-core';
+
+/** DI token for the current tenant context */
+declare const TENANT_CONTEXT: unique symbol;
+/** Tenant information resolved from the request */
+interface TenantInfo {
+    /** Unique tenant identifier */
+    id: string;
+    /** Optional tenant name */
+    name?: string;
+    /** Optional tenant-specific config/metadata */
+    metadata?: Record<string, any>;
+}
+/** Strategy for resolving the tenant from a request */
+type TenantResolutionStrategy = 'header' | 'subdomain' | 'path' | 'query' | ((req: any) => TenantInfo | null | Promise<TenantInfo | null>);
+interface MultiTenantOptions {
+    /**
+     * How to resolve the tenant from the request.
+     * - 'header' — reads X-Tenant-ID header (default)
+     * - 'subdomain' — extracts from subdomain (tenant.example.com)
+     * - 'path' — extracts from first path segment (/tenant-id/...)
+     * - 'query' — reads ?tenantId= query param
+     * - function — custom resolver
+     */
+    strategy?: TenantResolutionStrategy;
+    /** Header name when strategy is 'header' (default: 'x-tenant-id') */
+    headerName?: string;
+    /** Query param name when strategy is 'query' (default: 'tenantId') */
+    queryParam?: string;
+    /**
+     * Called after tenant is resolved. Use for validation, loading tenant
+     * config from DB, or rejecting unknown tenants.
+     */
+    onTenantResolved?: (tenant: TenantInfo, req: any) => void | Promise<void>;
+    /** Return a 403 if no tenant can be resolved (default: true) */
+    required?: boolean;
+    /** Routes to skip tenant resolution (e.g., health checks) */
+    excludeRoutes?: string[];
+}
+
+/**
+ * Multi-tenancy adapter for KickJS.
+ *
+ * Resolves the tenant from each request and makes it available
+ * via DI (`@Inject(TENANT_CONTEXT)`) and `req.tenant`.
+ *
+ * @example
+ * ```ts
+ * import { TenantAdapter, TENANT_CONTEXT } from '@forinda/kickjs-multi-tenant'
+ *
+ * bootstrap({
+ *   modules,
+ *   adapters: [
+ *     new TenantAdapter({
+ *       strategy: 'header',
+ *       onTenantResolved: async (tenant) => {
+ *         // Load tenant config from DB, validate, etc.
+ *       },
+ *     }),
+ *   ],
+ * })
+ *
+ * // In a service:
+ * @Service()
+ * class UserService {
+ *   constructor(@Inject(TENANT_CONTEXT) private tenant: TenantInfo) {}
+ * }
+ * ```
+ */
+declare class TenantAdapter implements AppAdapter {
+    name: string;
+    private options;
+    constructor(options?: MultiTenantOptions);
+    middleware(): AdapterMiddleware[];
+    beforeStart(_app: any, container: Container): void;
+    private resolveTenant;
+}
+
+export { type MultiTenantOptions, TENANT_CONTEXT, TenantAdapter, type TenantInfo, type TenantResolutionStrategy };

package/dist/index.js

@@ -0,0 +1,108 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/tenant.adapter.ts
+import { Logger, Scope } from "@forinda/kickjs-core";
+
+// src/types.ts
+var TENANT_CONTEXT = /* @__PURE__ */ Symbol("TenantContext");
+
+// src/tenant.adapter.ts
+var log = Logger.for("MultiTenant");
+var TenantAdapter = class {
+  static {
+    __name(this, "TenantAdapter");
+  }
+  name = "TenantAdapter";
+  options;
+  constructor(options = {}) {
+    this.options = {
+      strategy: options.strategy ?? "header",
+      required: options.required ?? true,
+      headerName: options.headerName ?? "x-tenant-id",
+      queryParam: options.queryParam ?? "tenantId",
+      ...options
+    };
+  }
+  middleware() {
+    return [
+      {
+        handler: /* @__PURE__ */ __name(async (req, res, next) => {
+          if (this.options.excludeRoutes?.some((r) => req.path.startsWith(r))) {
+            return next();
+          }
+          const tenant = await this.resolveTenant(req);
+          if (!tenant) {
+            if (this.options.required) {
+              res.status(403).json({
+                message: "Tenant not found. Provide a valid tenant identifier."
+              });
+              return;
+            }
+            return next();
+          }
+          ;
+          req.tenant = tenant;
+          if (this.options.onTenantResolved) {
+            await this.options.onTenantResolved(tenant, req);
+          }
+          next();
+        }, "handler"),
+        phase: "beforeGlobal"
+      }
+    ];
+  }
+  beforeStart(_app, container) {
+    container.registerFactory(TENANT_CONTEXT, () => ({
+      id: "default",
+      name: "Default Tenant"
+    }), Scope.SINGLETON);
+    log.info(`Tenant resolution: ${typeof this.options.strategy === "function" ? "custom" : this.options.strategy}`);
+  }
+  async resolveTenant(req) {
+    const strategy = this.options.strategy;
+    if (typeof strategy === "function") {
+      return strategy(req);
+    }
+    switch (strategy) {
+      case "header": {
+        const tenantId = req.get(this.options.headerName);
+        return tenantId ? {
+          id: tenantId
+        } : null;
+      }
+      case "subdomain": {
+        const host = req.hostname;
+        const parts = host.split(".");
+        if (parts.length >= 3) {
+          return {
+            id: parts[0]
+          };
+        }
+        return null;
+      }
+      case "path": {
+        const segments = req.path.split("/").filter(Boolean);
+        if (segments.length > 0) {
+          return {
+            id: segments[0]
+          };
+        }
+        return null;
+      }
+      case "query": {
+        const tenantId = req.query[this.options.queryParam];
+        return tenantId ? {
+          id: tenantId
+        } : null;
+      }
+      default:
+        return null;
+    }
+  }
+};
+export {
+  TENANT_CONTEXT,
+  TenantAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tenant.adapter.ts","../src/types.ts"],"sourcesContent":["import {\n  Logger,\n  type AppAdapter,\n  type AdapterMiddleware,\n  type Container,\n  Scope,\n} from '@forinda/kickjs-core'\nimport type { Request, Response, NextFunction } from 'express'\nimport {\n  TENANT_CONTEXT,\n  type TenantInfo,\n  type MultiTenantOptions,\n  type TenantResolutionStrategy,\n} from './types'\n\nconst log = Logger.for('MultiTenant')\n\n/**\n * Multi-tenancy adapter for KickJS.\n *\n * Resolves the tenant from each request and makes it available\n * via DI (`@Inject(TENANT_CONTEXT)`) and `req.tenant`.\n *\n * @example\n * ```ts\n * import { TenantAdapter, TENANT_CONTEXT } from '@forinda/kickjs-multi-tenant'\n *\n * bootstrap({\n *   modules,\n *   adapters: [\n *     new TenantAdapter({\n *       strategy: 'header',\n *       onTenantResolved: async (tenant) => {\n *         // Load tenant config from DB, validate, etc.\n *       },\n *     }),\n *   ],\n * })\n *\n * // In a service:\n * @Service()\n * class UserService {\n *   constructor(@Inject(TENANT_CONTEXT) private tenant: TenantInfo) {}\n * }\n * ```\n */\nexport class TenantAdapter implements AppAdapter {\n  name = 'TenantAdapter'\n  private options: Required<\n    Pick<MultiTenantOptions, 'strategy' | 'required' | 'headerName' | 'queryParam'>\n  > &\n    MultiTenantOptions\n\n  constructor(options: MultiTenantOptions = {}) {\n    this.options = {\n      strategy: options.strategy ?? 'header',\n      required: options.required ?? true,\n      headerName: options.headerName ?? 'x-tenant-id',\n      queryParam: options.queryParam ?? 'tenantId',\n      ...options,\n    }\n  }\n\n  middleware(): AdapterMiddleware[] {\n    return [\n      {\n        handler: async (req: Request, res: Response, next: NextFunction) => {\n          // Skip excluded routes\n          if (this.options.excludeRoutes?.some((r) => req.path.startsWith(r))) {\n            return next()\n          }\n\n          const tenant = await this.resolveTenant(req)\n\n          if (!tenant) {\n            if (this.options.required) {\n              res\n                .status(403)\n                .json({ message: 'Tenant not found. Provide a valid tenant identifier.' })\n              return\n            }\n            return next()\n          }\n\n          // Attach to request\n          ;(req as any).tenant = tenant\n\n          // Call hook\n          if (this.options.onTenantResolved) {\n            await this.options.onTenantResolved(tenant, req)\n          }\n\n          next()\n        },\n        phase: 'beforeGlobal',\n      },\n    ]\n  }\n\n  beforeStart(_app: any, container: Container): void {\n    // Register a factory that reads the tenant from the current request context\n    // This requires request-scoped resolution — for now, register as a placeholder\n    container.registerFactory(\n      TENANT_CONTEXT,\n      () => ({ id: 'default', name: 'Default Tenant' }) as TenantInfo,\n      Scope.SINGLETON,\n    )\n    log.info(\n      `Tenant resolution: ${typeof this.options.strategy === 'function' ? 'custom' : this.options.strategy}`,\n    )\n  }\n\n  private async resolveTenant(req: Request): Promise<TenantInfo | null> {\n    const strategy = this.options.strategy\n\n    if (typeof strategy === 'function') {\n      return strategy(req)\n    }\n\n    switch (strategy) {\n      case 'header': {\n        const tenantId = req.get(this.options.headerName)\n        return tenantId ? { id: tenantId } : null\n      }\n      case 'subdomain': {\n        const host = req.hostname\n        const parts = host.split('.')\n        if (parts.length >= 3) {\n          return { id: parts[0] }\n        }\n        return null\n      }\n      case 'path': {\n        const segments = req.path.split('/').filter(Boolean)\n        if (segments.length > 0) {\n          return { id: segments[0] }\n        }\n        return null\n      }\n      case 'query': {\n        const tenantId = req.query[this.options.queryParam] as string\n        return tenantId ? { id: tenantId } : null\n      }\n      default:\n        return null\n    }\n  }\n}\n","/** DI token for the current tenant context */\nexport const TENANT_CONTEXT = Symbol('TenantContext')\n\n/** Tenant information resolved from the request */\nexport interface TenantInfo {\n  /** Unique tenant identifier */\n  id: string\n  /** Optional tenant name */\n  name?: string\n  /** Optional tenant-specific config/metadata */\n  metadata?: Record<string, any>\n}\n\n/** Strategy for resolving the tenant from a request */\nexport type TenantResolutionStrategy =\n  | 'header'\n  | 'subdomain'\n  | 'path'\n  | 'query'\n  | ((req: any) => TenantInfo | null | Promise<TenantInfo | null>)\n\nexport interface MultiTenantOptions {\n  /**\n   * How to resolve the tenant from the request.\n   * - 'header' — reads X-Tenant-ID header (default)\n   * - 'subdomain' — extracts from subdomain (tenant.example.com)\n   * - 'path' — extracts from first path segment (/tenant-id/...)\n   * - 'query' — reads ?tenantId= query param\n   * - function — custom resolver\n   */\n  strategy?: TenantResolutionStrategy\n\n  /** Header name when strategy is 'header' (default: 'x-tenant-id') */\n  headerName?: string\n\n  /** Query param name when strategy is 'query' (default: 'tenantId') */\n  queryParam?: string\n\n  /**\n   * Called after tenant is resolved. Use for validation, loading tenant\n   * config from DB, or rejecting unknown tenants.\n   */\n  onTenantResolved?: (tenant: TenantInfo, req: any) => void | Promise<void>\n\n  /** Return a 403 if no tenant can be resolved (default: true) */\n  required?: boolean\n\n  /** Routes to skip tenant resolution (e.g., health checks) */\n  excludeRoutes?: string[]\n}\n"],"mappings":";;;;AAAA,SACEA,QAIAC,aACK;;;ACLA,IAAMC,iBAAiBC,uBAAO,eAAA;;;ADcrC,IAAMC,MAAMC,OAAOC,IAAI,aAAA;AA+BhB,IAAMC,gBAAN,MAAMA;EA9Cb,OA8CaA;;;EACXC,OAAO;EACCC;EAKR,YAAYA,UAA8B,CAAC,GAAG;AAC5C,SAAKA,UAAU;MACbC,UAAUD,QAAQC,YAAY;MAC9BC,UAAUF,QAAQE,YAAY;MAC9BC,YAAYH,QAAQG,cAAc;MAClCC,YAAYJ,QAAQI,cAAc;MAClC,GAAGJ;IACL;EACF;EAEAK,aAAkC;AAChC,WAAO;MACL;QACEC,SAAS,8BAAOC,KAAcC,KAAeC,SAAAA;AAE3C,cAAI,KAAKT,QAAQU,eAAeC,KAAK,CAACC,MAAML,IAAIM,KAAKC,WAAWF,CAAAA,CAAAA,GAAK;AACnE,mBAAOH,KAAAA;UACT;AAEA,gBAAMM,SAAS,MAAM,KAAKC,cAAcT,GAAAA;AAExC,cAAI,CAACQ,QAAQ;AACX,gBAAI,KAAKf,QAAQE,UAAU;AACzBM,kBACGS,OAAO,GAAA,EACPC,KAAK;gBAAEC,SAAS;cAAuD,CAAA;AAC1E;YACF;AACA,mBAAOV,KAAAA;UACT;;AAGEF,cAAYQ,SAASA;AAGvB,cAAI,KAAKf,QAAQoB,kBAAkB;AACjC,kBAAM,KAAKpB,QAAQoB,iBAAiBL,QAAQR,GAAAA;UAC9C;AAEAE,eAAAA;QACF,GA3BS;QA4BTY,OAAO;MACT;;EAEJ;EAEAC,YAAYC,MAAWC,WAA4B;AAGjDA,cAAUC,gBACRC,gBACA,OAAO;MAAEC,IAAI;MAAW5B,MAAM;IAAiB,IAC/C6B,MAAMC,SAAS;AAEjBlC,QAAImC,KACF,sBAAsB,OAAO,KAAK9B,QAAQC,aAAa,aAAa,WAAW,KAAKD,QAAQC,QAAQ,EAAE;EAE1G;EAEA,MAAce,cAAcT,KAA0C;AACpE,UAAMN,WAAW,KAAKD,QAAQC;AAE9B,QAAI,OAAOA,aAAa,YAAY;AAClC,aAAOA,SAASM,GAAAA;IAClB;AAEA,YAAQN,UAAAA;MACN,KAAK,UAAU;AACb,cAAM8B,WAAWxB,IAAIyB,IAAI,KAAKhC,QAAQG,UAAU;AAChD,eAAO4B,WAAW;UAAEJ,IAAII;QAAS,IAAI;MACvC;MACA,KAAK,aAAa;AAChB,cAAME,OAAO1B,IAAI2B;AACjB,cAAMC,QAAQF,KAAKG,MAAM,GAAA;AACzB,YAAID,MAAME,UAAU,GAAG;AACrB,iBAAO;YAAEV,IAAIQ,MAAM,CAAA;UAAG;QACxB;AACA,eAAO;MACT;MACA,KAAK,QAAQ;AACX,cAAMG,WAAW/B,IAAIM,KAAKuB,MAAM,GAAA,EAAKG,OAAOC,OAAAA;AAC5C,YAAIF,SAASD,SAAS,GAAG;AACvB,iBAAO;YAAEV,IAAIW,SAAS,CAAA;UAAG;QAC3B;AACA,eAAO;MACT;MACA,KAAK,SAAS;AACZ,cAAMP,WAAWxB,IAAIkC,MAAM,KAAKzC,QAAQI,UAAU;AAClD,eAAO2B,WAAW;UAAEJ,IAAII;QAAS,IAAI;MACvC;MACA;AACE,eAAO;IACX;EACF;AACF;","names":["Logger","Scope","TENANT_CONTEXT","Symbol","log","Logger","for","TenantAdapter","name","options","strategy","required","headerName","queryParam","middleware","handler","req","res","next","excludeRoutes","some","r","path","startsWith","tenant","resolveTenant","status","json","message","onTenantResolved","phase","beforeStart","_app","container","registerFactory","TENANT_CONTEXT","id","Scope","SINGLETON","info","tenantId","get","host","hostname","parts","split","length","segments","filter","Boolean","query"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@forinda/kickjs-multi-tenant",
+  "version": "0.6.0",
+  "description": "Multi-tenancy helpers for KickJS — tenant resolution, scoped DI, and database routing",
+  "keywords": [
+    "kickjs",
+    "multi-tenant",
+    "multitenancy",
+    "saas",
+    "tenant",
+    "middleware",
+    "typescript",
+    "@forinda/kickjs-core",
+    "@forinda/kickjs-http"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "@forinda/kickjs-core": "0.7.0",
+    "@forinda/kickjs-http": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "homepage": "https://forinda.github.io/kick-js/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forinda/kick-js.git",
+    "directory": "packages/multi-tenant"
+  },
+  "bugs": {
+    "url": "https://github.com/forinda/kick-js/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}