feat: mv Singleton from egg (#288)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
	- Added singleton management functionality to the application.
	- Enhanced logging capabilities for core system components.
- Introduced new methods for managing application-wide singleton
instances.

- **Improvements**
	- Expanded module exports to include singleton-related utilities.
	- Provided more explicit interfaces for accessing loggers.

- **Bug Fixes**
- Improved error handling and validation in singleton instance creation.

- **Tests**
- Added extensive test coverage for the `Singleton` class, validating
various creation scenarios.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: fengmk2

Diff for: package.json

@@ -7,9 +7,6 @@
   "engines": {
     "node": ">= 18.19.0"
   },
-  "tnpm": {
-    "mode": "npm"
-  },
   "description": "A core plugin framework based on @eggjs/koa",
   "scripts": {
     "clean": "rimraf dist",

Diff for: src/egg.ts

@@ -9,7 +9,7 @@ import type {
   MiddlewareFunc as KoaMiddlewareFunc,
   Next,
 } from '@eggjs/koa';
-import { EggConsoleLogger } from 'egg-logger';
+import { EggConsoleLogger, Logger } from 'egg-logger';
 import { RegisterOptions, ResourcesController, EggRouter as Router } from '@eggjs/router';
 import type { ReadyFunctionArg } from 'get-ready';
 import { BaseContextClass } from './base_context_class.js';
@@ -19,6 +19,9 @@ import { Lifecycle } from './lifecycle.js';
 import { EggLoader } from './loader/egg_loader.js';
 import utils from './utils/index.js';
 import { EggAppConfig } from './types.js';
+import {
+  Singleton, type SingletonCreateMethod, type SingletonOptions,
+} from './singleton.js';
 
 const debug = debuglog('@eggjs/core/egg');
 
@@ -185,6 +188,34 @@ export class EggCore extends KoaApplication {
     });
   }
 
+  get logger(): Logger {
+    return this.console;
+  }
+
+  get coreLogger(): Logger {
+    return this.console;
+  }
+
+  /**
+   * create a singleton instance
+   * @param {String} name - unique name for singleton
+   * @param {Function|AsyncFunction} create - method will be invoked when singleton instance create
+   */
+  addSingleton(name: string, create: SingletonCreateMethod) {
+    const options: SingletonOptions = {
+      name,
+      create,
+      app: this,
+    };
+    const singleton = new Singleton(options);
+    const initPromise = singleton.init();
+    if (initPromise) {
+      this.beforeStart(async () => {
+        await initPromise;
+      });
+    }
+  }
+
   /**
    * override koa's app.use, support generator function
    * @since 1.0.0

Diff for: src/index.ts

@@ -5,6 +5,7 @@ export { utils };
 export * from './egg.js';
 export * from './base_context_class.js';
 export * from './lifecycle.js';
+export * from './singleton.js';
 export * from './loader/egg_loader.js';
 export * from './loader/file_loader.js';
 export * from './loader/context_loader.js';

Diff for: src/singleton.ts

@@ -0,0 +1,149 @@
+import assert from 'node:assert';
+import { isAsyncFunction } from 'is-type-of';
+import type { EggCore } from './egg.js';
+
+export type SingletonCreateMethod =
+  (config: Record<string, any>, app: EggCore, clientName: string) => unknown | Promise<unknown>;
+
+export interface SingletonOptions {
+  name: string;
+  app: EggCore;
+  create: SingletonCreateMethod;
+}
+
+export class Singleton<T = any> {
+  readonly clients = new Map<string, T>();
+  readonly app: EggCore;
+  readonly create: SingletonCreateMethod;
+  readonly name: string;
+  readonly options: Record<string, any>;
+
+  constructor(options: SingletonOptions) {
+    assert(options.name, '[@eggjs/core/singleton] Singleton#constructor options.name is required');
+    assert(options.app, '[@eggjs/core/singleton] Singleton#constructor options.app is required');
+    assert(options.create, '[@eggjs/core/singleton] Singleton#constructor options.create is required');
+    assert(!(options.name in options.app), `[@eggjs/core/singleton] ${options.name} is already exists in app`);
+    this.app = options.app;
+    this.name = options.name;
+    this.create = options.create;
+    this.options = options.app.config[this.name] ?? {};
+  }
+
+  init() {
+    return isAsyncFunction(this.create) ? this.initAsync() : this.initSync();
+  }
+
+  initSync() {
+    const options = this.options;
+    assert(!(options.client && options.clients),
+      `[@eggjs/core/singleton] ${this.name} can not set options.client and options.clients both`);
+
+    // alias app[name] as client, but still support createInstance method
+    if (options.client) {
+      const client = this.createInstance(options.client, options.name);
+      this.#setClientToApp(client);
+      this.#extendDynamicMethods(client);
+      return;
+    }
+
+    // multi client, use app[name].getSingletonInstance(id)
+    if (options.clients) {
+      Object.keys(options.clients).forEach(id => {
+        const client = this.createInstance(options.clients[id], id);
+        this.clients.set(id, client);
+      });
+      this.#setClientToApp(this);
+      return;
+    }
+
+    // no config.clients and config.client
+    this.#setClientToApp(this);
+  }
+
+  async initAsync() {
+    const options = this.options;
+    assert(!(options.client && options.clients),
+      `[@eggjs/core/singleton] ${this.name} can not set options.client and options.clients both`);
+
+    // alias app[name] as client, but still support createInstance method
+    if (options.client) {
+      const client = await this.createInstanceAsync(options.client, options.name);
+      this.#setClientToApp(client);
+      this.#extendDynamicMethods(client);
+      return;
+    }
+
+    // multi client, use app[name].getInstance(id)
+    if (options.clients) {
+      await Promise.all(Object.keys(options.clients).map((id: string) => {
+        return this.createInstanceAsync(options.clients[id], id)
+          .then(client => this.clients.set(id, client));
+      }));
+      this.#setClientToApp(this);
+      return;
+    }
+
+    // no config.clients and config.client
+    this.#setClientToApp(this);
+  }
+
+  #setClientToApp(client: unknown) {
+    Reflect.set(this.app, this.name, client);
+  }
+
+  /**
+   * @deprecated please use `getSingletonInstance(id)` instead
+   */
+  get(id: string) {
+    return this.clients.get(id)!;
+  }
+
+  /**
+   * Get singleton instance by id
+   */
+  getSingletonInstance(id: string) {
+    return this.clients.get(id)!;
+  }
+
+  createInstance(config: Record<string, any>, clientName: string) {
+    // async creator only support createInstanceAsync
+    assert(!isAsyncFunction(this.create),
+      `[@eggjs/core/singleton] ${this.name} only support synchronous creation, please use createInstanceAsync`);
+    // options.default will be merge in to options.clients[id]
+    config = {
+      ...this.options.default,
+      ...config,
+    };
+    return (this.create as SingletonCreateMethod)(config, this.app, clientName) as T;
+  }
+
+  async createInstanceAsync(config: Record<string, any>, clientName: string) {
+    // options.default will be merge in to options.clients[id]
+    config = {
+      ...this.options.default,
+      ...config,
+    };
+    return await this.create(config, this.app, clientName) as T;
+  }
+
+  #extendDynamicMethods(client: any) {
+    assert(!client.createInstance, '[@eggjs/core/singleton] singleton instance should not have createInstance method');
+    assert(!client.createInstanceAsync, '[@eggjs/core/singleton] singleton instance should not have createInstanceAsync method');
+
+    try {
+      let extendable = client;
+      // Object.preventExtensions() or Object.freeze()
+      if (!Object.isExtensible(client) || Object.isFrozen(client)) {
+        // eslint-disable-next-line no-proto
+        extendable = client.__proto__ || client;
+      }
+      extendable.createInstance = this.createInstance.bind(this);
+      extendable.createInstanceAsync = this.createInstanceAsync.bind(this);
+    } catch (err) {
+      this.app.coreLogger.warn(
+        '[@eggjs/core/singleton] %s dynamic create is disabled because of client is un-extendable',
+        this.name);
+      this.app.coreLogger.warn(err);
+    }
+  }
+}

Diff for: test/egg.test.ts

@@ -34,6 +34,14 @@ describe('test/egg.test.ts', () => {
       assert.equal(app.options.baseDir, process.cwd());
     });
 
+    it('should export logger and coreLogger', () => {
+      app = new EggCore();
+      assert.equal(typeof app.logger.info, 'function');
+      assert.equal(typeof app.coreLogger.error, 'function');
+      app.logger.info('hello egg logger info level');
+      app.coreLogger.warn('hello egg coreLogger warn level');
+    });
+
     it('should set default application when no type', () => {
       app = new EggCore();
       assert.equal(app.type, 'application');

Diff for: test/index.test.ts

@@ -29,6 +29,7 @@ describe('test/index.test.ts', () => {
       'Request',
       'Response',
       'Router',
+      'Singleton',
       'Timing',
       'utils',
     ]);