@mxweb/core 1.0.0

package/dist/service.d.ts

@@ -0,0 +1,261 @@
+/**
+ * @fileoverview Service layer with dependency injection support.
+ *
+ * This module provides the base `Service` class and `service()` factory function
+ * for creating service classes with dependency injection. Services encapsulate
+ * business logic and can:
+ * - Access the current request context via `this.context`
+ * - Inject dependencies from the Application's injection container
+ * - Be injected into Controllers
+ *
+ * @module service
+ *
+ * @example
+ * ```ts
+ * import { service, Service } from "@mxweb/core";
+ *
+ * // Simple service without custom injections
+ * export class UtilityService extends Service {
+ *   formatDate(date: Date): string {
+ *     return date.toISOString();
+ *   }
+ * }
+ *
+ * // Service with dependency injection
+ * const ProductServiceBase = service((injects) => ({
+ *   db: injects.get("db") as DatabaseConnection,
+ *   cache: injects.get("cache") as CacheService,
+ * }));
+ *
+ * export class ProductService extends ProductServiceBase {
+ *   async findAll() {
+ *     const cached = await this.cache.get("products");
+ *     if (cached) return cached;
+ *
+ *     const products = await this.db.query("SELECT * FROM products");
+ *     await this.cache.set("products", products);
+ *     return products;
+ *   }
+ * }
+ * ```
+ */
+import { ApplicationInject } from "./common";
+import { ExecuteContext } from "./execute";
+/**
+ * Type for service injection configuration.
+ *
+ * Can be either:
+ * - A plain object with injection mappings
+ * - An async function that receives the injection container and returns mappings
+ *
+ * @typeParam T - The shape of the injection object
+ *
+ * @example
+ * ```ts
+ * // Plain object (static dependencies)
+ * const map: ServiceInjectMap<{ util: UtilService }> = {
+ *   util: new UtilService()
+ * };
+ *
+ * // Async function (dynamic dependencies from container)
+ * const map: ServiceInjectMap<{ db: Database }> = async (injects) => ({
+ *   db: injects.get("db") as Database
+ * });
+ * ```
+ */
+type ServiceInjectMap<T extends Record<string, unknown>> = T | ((injects: Map<string, unknown>) => T | Promise<T>);
+/**
+ * Transforms an injection map type into readonly instance properties.
+ * Used to provide type-safe access to injected dependencies.
+ *
+ * @typeParam T - The injection map object type
+ * @internal
+ */
+type InjectPropertiesByInstance<T extends Record<string, unknown>> = {
+    readonly [K in keyof T]: T[K];
+};
+/**
+ * Base class for all services in the application.
+ *
+ * Services encapsulate business logic and provide reusable functionality
+ * that can be shared across controllers. Features:
+ * - Access to the current request context (`this.context`)
+ * - Access to application-level injections (`this.getInject()`)
+ * - Lazy initialization of async dependencies
+ *
+ * @remarks
+ * For services without custom injections, extend `Service` directly.
+ * For services with injections, use the `service()` factory function.
+ *
+ * @example
+ * ```ts
+ * // Simple service
+ * class EmailService extends Service {
+ *   async sendEmail(to: string, subject: string, body: string) {
+ *     // Access request context if needed
+ *     const userId = this.context.user?.id;
+ *
+ *     // Access application-level inject
+ *     const mailer = this.getInject<Mailer>("mailer");
+ *
+ *     return mailer?.send({ to, subject, body, from: userId });
+ *   }
+ * }
+ * ```
+ */
+declare class BaseService {
+    /** Flag to track if async dependencies have been initialized */
+    private _initialized;
+    /**
+     * Access the current request's ExecuteContext.
+     *
+     * Provides access to request, response, params, query, body, and more.
+     * Uses AsyncLocalStorage to get the context for the current request.
+     *
+     * @returns The ExecuteContext for the current request
+     *
+     * @example
+     * ```ts
+     * class MyService extends Service {
+     *   async doSomething() {
+     *     const userId = this.context.params.id;
+     *     const query = this.context.query;
+     *     const body = await this.context.body();
+     *     return { userId, query, body };
+     *   }
+     * }
+     * ```
+     */
+    protected get context(): ExecuteContext;
+    /**
+     * Gets an application-level inject by name.
+     *
+     * @typeParam T - The type of the inject (defaults to ApplicationInject)
+     * @param name - The name of the inject to retrieve
+     * @returns The inject instance or undefined if not found
+     *
+     * @example
+     * ```ts
+     * class MyService extends Service {
+     *   async query(sql: string) {
+     *     const db = this.getInject<Database>("db");
+     *     if (!db) throw new Error("Database not configured");
+     *     return db.query(sql);
+     *   }
+     * }
+     * ```
+     */
+    protected getInject<T extends ApplicationInject = ApplicationInject>(name: string): T | undefined;
+    /**
+     * Initializes async dependencies for this service.
+     *
+     * Called automatically before the service is used. Resolves the injection
+     * map (if defined) and assigns dependencies to instance properties.
+     *
+     * @remarks
+     * This method is idempotent - calling it multiple times has no effect
+     * after the first initialization. Results are cached per service class.
+     *
+     * @internal
+     */
+    _initDependencies(): Promise<void>;
+}
+/**
+ * Factory function to create a Service base class with dependency injection.
+ *
+ * Use this function when your service needs access to specific dependencies
+ * from the application's injection container. The function receives the
+ * injection map and returns dependencies as typed instance properties.
+ *
+ * @typeParam T - The shape of the injection object
+ * @param map - Injection configuration (object or async function)
+ * @returns A new class that extends BaseService with typed injection properties
+ *
+ * @example
+ * ```ts
+ * // Create a base with database and cache injections
+ * const ProductServiceBase = service((injects) => ({
+ *   db: injects.get("db") as DatabaseConnection,
+ *   cache: injects.get("cache") as CacheService,
+ * }));
+ *
+ * // Extend the base to create your service
+ * export class ProductService extends ProductServiceBase {
+ *   async findAll() {
+ *     // TypeScript knows this.db and this.cache types
+ *     const cached = await this.cache.get("products");
+ *     if (cached) return cached;
+ *
+ *     const products = await this.db.query("SELECT * FROM products");
+ *     await this.cache.set("products", products, 3600);
+ *     return products;
+ *   }
+ *
+ *   async findById(id: string) {
+ *     return this.db.query("SELECT * FROM products WHERE id = ?", [id]);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Using static object mapping
+ * const UtilServiceBase = service({
+ *   logger: new Logger(),
+ *   validator: new Validator(),
+ * });
+ *
+ * export class UtilService extends UtilServiceBase {
+ *   log(message: string) {
+ *     this.logger.info(message);
+ *   }
+ * }
+ * ```
+ */
+export declare function service<T extends Record<string, unknown>>(map: ServiceInjectMap<T>): new () => BaseService & InjectPropertiesByInstance<T>;
+/**
+ * Base Service class without custom injections.
+ *
+ * Extend this class directly when your service doesn't need
+ * dependency injection beyond what's available via `this.context`
+ * and `this.getInject()`.
+ *
+ * @example
+ * ```ts
+ * import { Service } from "@mxweb/core";
+ *
+ * export class ValidationService extends Service {
+ *   isValidEmail(email: string): boolean {
+ *     return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+ *   }
+ *
+ *   isValidPhone(phone: string): boolean {
+ *     return /^\+?[\d\s-]{10,}$/.test(phone);
+ *   }
+ *
+ *   async validateRequest() {
+ *     const body = await this.context.body<{ email: string }>();
+ *     return this.isValidEmail(body.email);
+ *   }
+ * }
+ * ```
+ */
+export declare const Service: typeof BaseService;
+/**
+ * Type representing a Service class constructor.
+ *
+ * Used for typing service classes in injection configurations.
+ *
+ * @typeParam T - The service instance type
+ *
+ * @example
+ * ```ts
+ * function createService<T extends BaseService>(
+ *   ServiceClass: ServiceConstructor<T>
+ * ): T {
+ *   return new ServiceClass();
+ * }
+ * ```
+ */
+export type ServiceConstructor<T extends BaseService> = new () => T;
+export {};

package/dist/service.js

@@ -0,0 +1 @@
+"use strict";var t=require("./context.js");const e=new WeakMap;class i{constructor(){this._initialized=!1}get context(){return t.executeContext}getInject(e){return t.executeContext.getInject(e)}async _initDependencies(){if(this._initialized)return;const i=this.constructor.injectMap;if(!i)return void(this._initialized=!0);let n;e.has(this.constructor)?n=e.get(this.constructor):(n="function"==typeof i?await i(t.executeContext.injections):i,e.set(this.constructor,n));for(const[t,e]of Object.entries(n))this[t]=e;this._initialized=!0}}const n=i;exports.Service=n,exports.service=function(t){var e;return(e=class extends i{}).injectMap=t,e};

package/dist/service.mjs

@@ -0,0 +1 @@
+import{executeContext as t}from"./context.mjs";const i=new WeakMap;class n{constructor(){this._initialized=!1}get context(){return t}getInject(i){return t.getInject(i)}async _initDependencies(){if(this._initialized)return;const n=this.constructor.injectMap;if(!n)return void(this._initialized=!0);let e;i.has(this.constructor)?e=i.get(this.constructor):(e="function"==typeof n?await n(t.injections):n,i.set(this.constructor,e));for(const[t,i]of Object.entries(e))this[t]=i;this._initialized=!0}}function e(t){var i;return(i=class extends n{}).injectMap=t,i}const s=n;export{s as Service,e as service};

package/package.json

@@ -0,0 +1,168 @@
+{
+  "name": "@mxweb/core",
+  "version": "1.0.0",
+  "description": "A NestJS-inspired backend framework for Next.js App Router with dependency injection, guards, interceptors, and modular architecture",
+  "keywords": [
+    "nextjs",
+    "next",
+    "nestjs",
+    "framework",
+    "backend",
+    "api",
+    "rest",
+    "dependency-injection",
+    "guards",
+    "interceptors",
+    "pipes",
+    "filters",
+    "decorators",
+    "controllers",
+    "services",
+    "app-router",
+    "typescript"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "author": "MXWeb Team <mxwebio@gmail.com>",
+  "homepage": "https://docs.mxweb.io/core",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@mxweb/utils": "^0.0.4",
+    "@rollup/plugin-babel": "^6.1.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^20",
+    "@typescript-eslint/eslint-plugin": "^8.49.0",
+    "@typescript-eslint/parser": "^8.49.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "glob": "^13.0.0",
+    "next": "16.0.10",
+    "prettier": "^3.7.4",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.53.4",
+    "typescript": "^5"
+  },
+  "peerDependencies": {
+    "@mxweb/utils": "^0.0.4",
+    "next": ">=16.0.10"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "yarn clean && yarn lint && rollup -c",
+    "build:watch": "rollup -c -w",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,json,md}\"",
+    "prepublishOnly": "yarn build"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    },
+    "./application": {
+      "types": "./dist/application.d.ts",
+      "import": "./dist/application.mjs",
+      "require": "./dist/application.js",
+      "default": "./dist/application.mjs"
+    },
+    "./common": {
+      "types": "./dist/common.d.ts",
+      "import": "./dist/common.mjs",
+      "require": "./dist/common.js",
+      "default": "./dist/common.mjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.mjs",
+      "require": "./dist/config.js",
+      "default": "./dist/config.mjs"
+    },
+    "./controller": {
+      "types": "./dist/controller.d.ts",
+      "import": "./dist/controller.mjs",
+      "require": "./dist/controller.js",
+      "default": "./dist/controller.mjs"
+    },
+    "./decorator": {
+      "types": "./dist/decorator.d.ts",
+      "import": "./dist/decorator.mjs",
+      "require": "./dist/decorator.js",
+      "default": "./dist/decorator.mjs"
+    },
+    "./error": {
+      "types": "./dist/error.d.ts",
+      "import": "./dist/error.mjs",
+      "require": "./dist/error.js",
+      "default": "./dist/error.mjs"
+    },
+    "./execute": {
+      "types": "./dist/execute.d.ts",
+      "import": "./dist/execute.mjs",
+      "require": "./dist/execute.js",
+      "default": "./dist/execute.mjs"
+    },
+    "./feature": {
+      "types": "./dist/feature.d.ts",
+      "import": "./dist/feature.mjs",
+      "require": "./dist/feature.js",
+      "default": "./dist/feature.mjs"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.mjs",
+      "require": "./dist/hooks.js",
+      "default": "./dist/hooks.mjs"
+    },
+    "./logger": {
+      "types": "./dist/logger.d.ts",
+      "import": "./dist/logger.mjs",
+      "require": "./dist/logger.js",
+      "default": "./dist/logger.mjs"
+    },
+    "./response": {
+      "types": "./dist/response.d.ts",
+      "import": "./dist/response.mjs",
+      "require": "./dist/response.js",
+      "default": "./dist/response.mjs"
+    },
+    "./route": {
+      "types": "./dist/route.d.ts",
+      "import": "./dist/route.mjs",
+      "require": "./dist/route.js",
+      "default": "./dist/route.mjs"
+    },
+    "./router": {
+      "types": "./dist/router.d.ts",
+      "import": "./dist/router.mjs",
+      "require": "./dist/router.js",
+      "default": "./dist/router.mjs"
+    },
+    "./service": {
+      "types": "./dist/service.d.ts",
+      "import": "./dist/service.mjs",
+      "require": "./dist/service.js",
+      "default": "./dist/service.mjs"
+    }
+  }
+}