@difizen/libro-common 0.3.4 → 1.0.0

package/src/ioc/contribution/index.spec.ts

@@ -0,0 +1,174 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import 'reflect-metadata';
+import assert from 'assert';
+
+import { GlobalContainer } from '../container';
+import { register } from '../container';
+import { Contribution, contrib } from './index';
+import { Syringe } from '../core';
+import { inject, singleton } from '../decorator';
+import { Module } from '../module/index';
+
+import { DefaultContributionProvider } from './contribution-provider';
+
+import { ContributionOptionConfig } from './index';
+
+describe('contribution', () => {
+  it('#register contribution', () => {
+    const FooContribution = Syringe.defineToken('FooContribution');
+    Contribution.register(register, FooContribution);
+    const provider = GlobalContainer.getNamed(Contribution.Provider, FooContribution);
+    assert(provider instanceof DefaultContributionProvider);
+    assert(GlobalContainer.isBoundNamed(Contribution.Provider, FooContribution));
+  });
+  it('#contrib decorator', () => {
+    const FooContribution = Syringe.defineToken('FooContribution');
+    const BarContribution = Syringe.defineToken('BarContribution');
+    Contribution.register(register, FooContribution);
+    @singleton({ contrib: FooContribution })
+    class Foo {}
+    @singleton({ contrib: [FooContribution, BarContribution] })
+    class Foo1 {}
+    register(Foo);
+    register(Foo1);
+    @singleton()
+    class Bar {
+      public contribs: Contribution.Provider<any>;
+      public bar: Contribution.Provider<any>;
+
+      constructor(
+        @contrib(FooContribution) contribs: Contribution.Provider<any>,
+        @inject(BarContribution) bar: Contribution.Provider<any>,
+      ) {
+        this.contribs = contribs;
+        this.bar = bar;
+      }
+    }
+    register(Bar);
+
+    const bar = GlobalContainer.get(Bar);
+    const list = bar.contribs.getContributions();
+    assert(bar.bar instanceof Foo1);
+    assert(list.length === 2);
+    assert(list.find((item) => item instanceof Foo));
+  });
+  it('#contribution option', () => {
+    const FooContribution = Syringe.defineToken('FooContribution');
+    @singleton({ contrib: FooContribution })
+    class Foo {}
+    register(Foo);
+    const childContainer = GlobalContainer.createChild();
+    Contribution.register(
+      childContainer.register.bind(childContainer),
+      FooContribution,
+      {
+        cache: true,
+      },
+    );
+    @singleton()
+    class Bar {
+      public pr: Contribution.Provider<any>;
+      constructor(@contrib(FooContribution) pr: Contribution.Provider<any>) {
+        this.pr = pr;
+      }
+    }
+    childContainer.register(Bar);
+    @singleton({ contrib: FooContribution })
+    class Foo1 {}
+    childContainer.register(Foo1);
+
+    const bar = childContainer.get(Bar);
+    const list = bar.pr.getContributions();
+
+    assert(list.length === 1);
+    assert(list.find((item) => item instanceof Foo1));
+    const cachelist = bar.pr.getContributions();
+    assert(list === cachelist);
+    const newlist = bar.pr.getContributions({ cache: false });
+    assert(list !== newlist && newlist.length === 1);
+    assert(newlist.find((item) => item instanceof Foo1));
+    const all = bar.pr.getContributions({ recursive: true, cache: false });
+    assert(all !== newlist && all.length === 2);
+    assert(all.find((item) => item instanceof Foo));
+    assert(all.find((item) => item instanceof Foo1));
+  });
+
+  it('#contribution event', () => {
+    const FooContribution = Syringe.defineToken('FooContribution');
+    @singleton({ contrib: FooContribution })
+    class Foo {}
+    register(Foo);
+    const childContainer = GlobalContainer.createChild();
+    Contribution.register(
+      childContainer.register.bind(childContainer),
+      FooContribution,
+      {
+        cache: true,
+      },
+    );
+    @singleton()
+    class Bar {
+      contributionChanged = false;
+      public pr: Contribution.Provider<any>;
+      constructor(@contrib(FooContribution) pr: Contribution.Provider<any>) {
+        this.pr = pr;
+        this.pr.onChanged(() => {
+          this.contributionChanged = true;
+        });
+      }
+    }
+    childContainer.register(Bar);
+    const bar = childContainer.get(Bar);
+
+    @singleton({ contrib: FooContribution })
+    class Foo1 {}
+    childContainer.register(Foo1);
+
+    assert(bar.contributionChanged);
+  });
+
+  it('#contirbution config', () => {
+    ContributionOptionConfig.recursive = true;
+    const p = GlobalContainer.createChild();
+    const fooContainer = p.createChild();
+    const barContainer = p.createChild();
+    const DemoContribution = Syringe.defineToken('FooContribution');
+    interface DemoContribution {
+      name: string;
+    }
+    @singleton({ contrib: DemoContribution })
+    class Foo implements DemoContribution {
+      name = 'foo';
+    }
+
+    @singleton({ contrib: DemoContribution })
+    class Bar implements DemoContribution {
+      name = 'bar';
+    }
+
+    @singleton({ contrib: DemoContribution })
+    class Baz implements DemoContribution {
+      name = 'baz';
+    }
+    const BazModule = Module().register(Baz);
+    const FooModule = Module().register(Foo).contribution(DemoContribution);
+    const BarModule = Module().register(Bar).contribution(DemoContribution);
+    p.load(BazModule);
+    fooContainer.load(FooModule);
+    barContainer.load(BarModule);
+    const fooProvider = fooContainer.getNamed<Contribution.Provider<DemoContribution>>(
+      Contribution.Provider,
+      DemoContribution,
+    );
+    const barProvider = barContainer.getNamed<Contribution.Provider<DemoContribution>>(
+      Contribution.Provider,
+      DemoContribution,
+    );
+    const foos = fooProvider.getContributions();
+    assert(foos.length === 2);
+    assert(foos.find((item) => item.name === 'foo'));
+    assert(foos.find((item) => item.name === 'baz'));
+    assert(barProvider.getContributions().length === 2);
+  });
+});

package/src/ioc/contribution/index.ts

@@ -0,0 +1,13 @@
+import * as Protocol from './contribution-protocol';
+import { contributionRegister } from './contribution-register';
+
+export * from './contribution-protocol';
+export * from './contribution-provider';
+export * from './decorator';
+
+export namespace Contribution {
+  export type Option = Protocol.Option;
+  export type Provider<T extends Record<string, any>> = Protocol.Provider<T>;
+  export const Provider = Protocol.Provider;
+  export const register = contributionRegister;
+}

package/src/ioc/core.ts

@@ -0,0 +1,198 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-shadow */
+
+import 'reflect-metadata';
+import type { Event, Newable, Abstract } from '../common/index.js';
+
+export type TokenOption = {
+  multiple?: boolean;
+  global?: boolean;
+};
+
+export type Decorator<T> = (target: Newable<T> | Abstract<T>) => any;
+
+export namespace Syringe {
+  /**
+   * 定义注入标识，默认允许多重注入
+   */
+  export const defineToken = (
+    name: string,
+    option: Partial<TokenOption> = { multiple: true, global: false },
+  ) => new Syringe.DefinedToken(name, option);
+  export class DefinedToken {
+    /**
+     * 兼容 inversify identifier
+     */
+    prototype: any = {};
+    protected name: string;
+    readonly multiple: boolean;
+    readonly symbol: symbol;
+    constructor(name: string, option: Partial<TokenOption> = {}) {
+      const { multiple = false, global } = option;
+      this.name = name;
+      this.symbol = global ? Symbol.for(this.name) : Symbol(this.name);
+      this.multiple = multiple;
+    }
+  }
+
+  export type Register = <T = any>(
+    token: Syringe.Token<T> | Syringe.InjectOption<T>,
+    options?: Syringe.InjectOption<T>,
+  ) => void;
+
+  export type Token<T> = string | symbol | Newable<T> | Abstract<T> | DefinedToken;
+  export type Named = string | symbol | DefinedToken;
+  export type NamedToken<T> = {
+    token: Token<T>;
+    named: Named;
+  };
+  export type OverrideToken<T> = {
+    token: Token<T>;
+    override: boolean;
+  };
+
+  export type Registry = (register: Register) => void;
+  export type Module = {
+    id: number;
+    name?: string;
+  };
+
+  export function isModule(data: Record<any, any> | undefined): data is Module {
+    return !!data && typeof data === 'object' && 'id' in data;
+  }
+
+  export type Container = {
+    parent?: Container | undefined;
+    remove: <T>(token: Syringe.Token<T>) => void;
+    register: <T = any>(
+      token: Syringe.Token<T> | Syringe.InjectOption<T>,
+      options?: Syringe.InjectOption<T>,
+    ) => void;
+    load: (module: Module, force?: boolean, deep?: boolean) => void;
+    unload: (module: Module) => void;
+    get: <T>(token: Syringe.Token<T>) => T;
+    getNamed: <T>(token: Syringe.Token<T>, named: Syringe.Named) => T;
+    getAll: <T>(token: Syringe.Token<T>) => T[];
+    getAllNamed: <T>(token: Syringe.Token<T>, named: Syringe.Named) => T[];
+    isBound: <T>(token: Syringe.Token<T>) => boolean;
+    isBoundNamed: <T>(token: Syringe.Token<T>, named: Syringe.Named) => boolean;
+    createChild: () => Container;
+    onModuleChanged: Event<void>;
+    onRegistered: Event<void>;
+  };
+
+  export type Context = {
+    container: Container;
+  };
+  export const ContextToken: Token<Context> = Symbol('Context');
+  export type UnionToken<T> = Token<T> | NamedToken<T>;
+  export type Class<T> = Newable<T>;
+  export type Factory<T> = (ctx: Context) => (...args: any) => T;
+  export type Dynamic<T> = (ctx: Context) => T;
+  export type MaybeArray<T> = T | T[];
+
+  export type DecoratorOption<T> = {
+    token?: MaybeArray<UnionToken<T>>;
+    contrib?: MaybeArray<Token<T>>;
+    lifecycle?: Lifecycle;
+  };
+
+  export type TargetOption<T> = {
+    contrib?: MaybeArray<Token<T>>;
+  } & ValueOption<T>;
+
+  export type ValueOption<T> = {
+    useClass?: MaybeArray<Class<T>>;
+    useDynamic?: MaybeArray<Dynamic<T>>;
+    useFactory?: MaybeArray<Factory<T>>;
+    useValue?: T;
+  };
+
+  export type InjectOption<T> = DecoratorOption<T> & ValueOption<T>;
+
+  export enum Lifecycle {
+    singleton = 'singleton',
+    transient = 'transient',
+  }
+  export const ClassOptionSymbol = Symbol.for('SyringeClassOption');
+
+  export type FormattedInjectOption<T> = {
+    token: UnionToken<T>[];
+    contrib: Token<T>[];
+    useClass: Class<T>[];
+    lifecycle: Lifecycle;
+    useDynamic: Dynamic<T>[];
+    useFactory: Factory<T>[];
+    useValue?: T;
+  } & InjectOption<T>;
+
+  export const DefaultOption: Syringe.InjectOption<any> = {
+    lifecycle: Lifecycle.transient,
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export namespace Utils {
+  export function toArray<T>(maybeArray: Syringe.MaybeArray<T> | undefined): T[] {
+    if (Array.isArray(maybeArray)) {
+      return maybeArray;
+    }
+    if (maybeArray === undefined) {
+      return [];
+    }
+    return [maybeArray];
+  }
+  export function isClass(
+    data?: string | symbol | Record<string, any>,
+  ): data is Syringe.Class<any> {
+    return !!(data && typeof data === 'function' && 'prototype' in data);
+  }
+  export function isDefinedToken(
+    data: Record<string, any> | undefined | symbol | string | number,
+  ): data is Syringe.DefinedToken {
+    return !!(
+      data &&
+      typeof data === 'object' &&
+      'symbol' in data &&
+      'multiple' in data
+    );
+  }
+  export function isInjectOption<T>(
+    data: Syringe.Token<T> | Syringe.InjectOption<T> | undefined,
+  ): data is Syringe.InjectOption<T> {
+    return !!(data && typeof data === 'object' && 'token' in data);
+  }
+
+  export function isNamedToken<T>(
+    data: Syringe.UnionToken<T> | undefined,
+  ): data is Syringe.NamedToken<T> {
+    return !!(data && typeof data === 'object' && 'token' in data && 'named' in data);
+  }
+  export function isMultipleEnabled<T>(token: Syringe.Token<T>): boolean {
+    return Utils.isDefinedToken(token) && token.multiple;
+  }
+
+  export function toRegistryOption<P>(
+    options: Syringe.InjectOption<P>,
+  ): Syringe.FormattedInjectOption<P> {
+    const token = Utils.toArray(options.token);
+    const useClass = Utils.toArray(options.useClass);
+    const useDynamic = Utils.toArray(options.useDynamic);
+    const useFactory = Utils.toArray(options.useFactory);
+    const contrib = Utils.toArray(options.contrib);
+    const lifecycle = options.lifecycle || Syringe.Lifecycle.transient;
+
+    const generalOption: Syringe.FormattedInjectOption<P> = {
+      token,
+      useClass,
+      lifecycle: contrib.length > 0 ? Syringe.Lifecycle.singleton : lifecycle,
+      contrib,
+      useDynamic,
+      useFactory,
+    };
+    if ('useValue' in options) {
+      generalOption.useValue = options.useValue;
+    }
+    return generalOption;
+  }
+}

package/src/ioc/decorator.spec.ts

@@ -0,0 +1,43 @@
+import assert from 'assert';
+
+import { Syringe } from './core';
+import { singleton, transient, injectable } from './decorator';
+
+describe('decorator', () => {
+  it('#injectable without option', () => {
+    @injectable()
+    class Foo {}
+    const option = Reflect.getMetadata(Syringe.ClassOptionSymbol, Foo);
+    assert(option.target === Foo);
+  });
+  it('#injectable with option', () => {
+    const FooSymbol = Symbol('FooSymbol');
+    @injectable({ token: FooSymbol, lifecycle: Syringe.Lifecycle.singleton })
+    class Foo {}
+    const option: Syringe.DecoratorOption<Foo> = Reflect.getMetadata(
+      Syringe.ClassOptionSymbol,
+      Foo,
+    );
+    assert(option.token === FooSymbol);
+  });
+  it('#singleton', () => {
+    const FooSymbol = Symbol('FooSymbol');
+    @singleton({ token: FooSymbol })
+    class Foo {}
+    const option: Syringe.InjectOption<Foo> = Reflect.getMetadata(
+      Syringe.ClassOptionSymbol,
+      Foo,
+    );
+    assert(option.lifecycle === Syringe.Lifecycle.singleton);
+  });
+  it('#transient', () => {
+    const FooSymbol = Symbol('FooSymbol');
+    @transient({ token: FooSymbol })
+    class Foo {}
+    const option: Syringe.InjectOption<Foo> = Reflect.getMetadata(
+      Syringe.ClassOptionSymbol,
+      Foo,
+    );
+    assert(option.lifecycle === Syringe.Lifecycle.transient);
+  });
+});

package/src/ioc/decorator.ts

@@ -0,0 +1,54 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+  injectable as inversInjectable,
+  inject as inversifyInject,
+  named as inversifyNamed,
+} from 'inversify';
+
+import type { Decorator } from './core';
+import { Syringe } from './core';
+import { namedToIdentifier, tokenToIdentifier } from './inversify-api';
+
+export function injectable<T = any>(
+  option: Syringe.DecoratorOption<T> = {},
+): Decorator<T> {
+  const decorator = inversInjectable();
+  return (target: any) => {
+    Reflect.defineMetadata(Syringe.ClassOptionSymbol, { ...option, target }, target);
+    decorator(target);
+  };
+}
+
+export function singleton<T = any>(
+  option: Syringe.DecoratorOption<T> = {},
+): Decorator<T> {
+  return (target, ...args) => {
+    injectable({ ...option, lifecycle: Syringe.Lifecycle.singleton })(target, ...args);
+    return target;
+  };
+}
+
+export function transient<T = any>(
+  option: Syringe.DecoratorOption<T> = {},
+): Decorator<T> {
+  return (target, ...args) => {
+    injectable({ ...option, lifecycle: Syringe.Lifecycle.transient })(target, ...args);
+    return target;
+  };
+}
+
+export function inject(
+  token: Syringe.Token<any>,
+  // Typescript 5 makes type-checking more accurate for decorators under --experimentalDecorators,
+  // We can get a type error: Parameters of type undefined cannot be assigned to parameters of type string,
+  // Let's leave the targetKey type loose and wait for inversify to fix the type problem.
+): (target: any, targetKey: any, index?: number | undefined) => void {
+  return inversifyInject(tokenToIdentifier(token));
+}
+export function named(
+  name: Syringe.Named,
+): (target: any, targetKey: any, index?: number | undefined) => void {
+  return inversifyNamed(namedToIdentifier(name));
+}
+export { postConstruct, optional, unmanaged, decorate } from 'inversify';

package/src/ioc/features/auto-factory.spec.ts

@@ -0,0 +1,90 @@
+import assert from 'assert';
+
+import { GlobalContainer } from '../container';
+import { inject, singleton } from '../decorator';
+
+import type { ToAutoFactory } from './auto-factory';
+import { autoFactory, AutoFactoryOption, toAutoFactory } from './auto-factory';
+
+describe('auto factory', () => {
+  it('#decorator', async () => {
+    @autoFactory()
+    class DataModel {
+      data: number;
+      constructor(@inject(AutoFactoryOption) option: { data: number }) {
+        this.data = option.data;
+      }
+    }
+
+    GlobalContainer.register(DataModel);
+    const factoryToken = toAutoFactory(DataModel);
+    const factory = GlobalContainer.get(factoryToken);
+    const model = factory({ data: 1 });
+    assert(model.data === 1);
+  });
+
+  it('#decorator extend', async () => {
+    @autoFactory()
+    class DataModelBase {
+      data: number;
+      constructor(@inject(AutoFactoryOption) option: { data: number }) {
+        this.data = option.data;
+      }
+    }
+
+    @autoFactory()
+    class DataModel extends DataModelBase {
+      count: number;
+      constructor(@inject(AutoFactoryOption) option: { data: number; count: number }) {
+        super(option);
+        this.count = option.count;
+      }
+    }
+    GlobalContainer.register(DataModelBase);
+    const factoryTokenBase = toAutoFactory(DataModelBase);
+    const factoryBase = GlobalContainer.get(factoryTokenBase);
+    const modelBase = factoryBase({ data: 1 });
+    assert(modelBase instanceof DataModelBase);
+    assert(modelBase.data === 1);
+
+    GlobalContainer.register(DataModel);
+    const factoryToken = toAutoFactory(DataModel);
+    const factory = GlobalContainer.get(factoryToken);
+    const model = factory({ data: 1, count: 2 });
+    assert(model instanceof DataModel);
+    assert(model instanceof DataModelBase);
+    assert(model.data === 1);
+    assert(model.count === 2);
+  });
+
+  it('#use factory', async () => {
+    @autoFactory()
+    class DataModel {
+      data: number;
+      constructor(@inject(AutoFactoryOption) option: { data: number }) {
+        this.data = option.data;
+      }
+    }
+
+    toAutoFactory<typeof DataModel>(DataModel);
+
+    @singleton()
+    class DataModelManager {
+      @inject(toAutoFactory(DataModel))
+      dataModelFactory: ToAutoFactory<typeof DataModel>;
+      // Factory<DataModel>
+      create(option: { data: number }) {
+        const data = this.dataModelFactory(option);
+        return data;
+      }
+    }
+
+    GlobalContainer.register(DataModel);
+    GlobalContainer.register(DataModelManager);
+
+    const dataManager = GlobalContainer.get(DataModelManager);
+    const data = dataManager.create({ data: 1 });
+    assert(data instanceof DataModel);
+    assert(data.data === 1);
+  });
+});

package/src/ioc/features/auto-factory.ts

@@ -0,0 +1,44 @@
+import type { Newable } from '../../common/index.js';
+import { Syringe } from '../core.js';
+import { transient } from '../decorator.js';
+import { registerSideOption } from '../side-option.js';
+
+export const AutoFactoryOption = Syringe.defineToken('AutoFactoryOption');
+export const AutoFactoryMeta = Syringe.defineToken('AutoFactoryMeta', {
+  multiple: false,
+});
+
+export function autoFactory<T = any>() {
+  return (target: Newable<T>): void => {
+    const AutoFactoryToken = Symbol();
+    Reflect.defineMetadata(AutoFactoryMeta, AutoFactoryToken, target);
+    transient()(target);
+    registerSideOption(
+      {
+        token: AutoFactoryToken,
+        useFactory: (ctx: Syringe.Context) => {
+          return (option: any) => {
+            const child = ctx.container.createChild();
+            child.register({ token: AutoFactoryOption, useValue: option });
+            return child.get(target);
+          };
+        },
+      },
+      target,
+    );
+  };
+}
+
+export type ToAutoFactory<T extends Newable<any>> = (
+  option: ConstructorParameters<T>[0],
+) => InstanceType<T>;
+
+export const toAutoFactory = <T extends Newable<any>>(
+  target: T,
+): Syringe.Token<(...args: ConstructorParameters<T>) => InstanceType<T>> => {
+  const factoryToken = Reflect.getOwnMetadata(AutoFactoryMeta, target);
+  if (!factoryToken) {
+    throw new Error(`Cannot find factory token for ${target.constructor.name}`);
+  }
+  return factoryToken;
+};

package/src/ioc/features/prioritized-contribution.ts

@@ -0,0 +1,43 @@
+import { Priority } from '../../common/index.js';
+import type { Newable } from '../../common/index.js';
+import type { Contribution } from '../contribution/index';
+import { Syringe } from '../core.js';
+import { singleton } from '../decorator.js';
+import { registerSideOption } from '../side-option.js';
+
+export interface PrioritizedContribution<O = any, T = any> {
+  canHandle: (option: O) => number;
+  handle: (option: O) => T;
+}
+
+@singleton()
+export class PrioritizedContributionManager<
+  O = any,
+  T extends PrioritizedContribution<O> = PrioritizedContribution,
+> {
+  protected findContribution(option: O, provider: Contribution.Provider<T>): T {
+    const prioritized = Priority.sortSync(provider.getContributions(), (contribution) =>
+      contribution.canHandle(option),
+    );
+    const sorted = prioritized.map((c) => c.value);
+    return sorted[0];
+  }
+}
+
+export const prioritizedContributionFactory = <O = any, T = any>() => {
+  return (
+    token: Syringe.Token<PrioritizedContribution<O, T>>,
+    contribution: PrioritizedContribution<O, T>,
+  ) => {
+    return (target: Newable<T>): void => {
+      registerSideOption(
+        {
+          token: token,
+          useValue: contribution,
+          lifecycle: Syringe.Lifecycle.singleton,
+        },
+        target,
+      );
+    };
+  };
+};

package/src/ioc/index.ts

@@ -0,0 +1,8 @@
+export * from './decorator';
+export * from './container';
+export * from './module';
+export * from './contribution';
+export * from './core';
+export * from './side-option';
+export * from './features/auto-factory';
+export * from './features/prioritized-contribution';