@declaro/core 2.0.0-beta.8 → 2.0.0-y.0

package/src/context/context.ts

@@ -1,60 +1,367 @@
+import { EventManager, type IEvent } from '../events/event-manager'
+import type { Class, PromiseOrValue, UnwrapPromise } from '../typescript'
 import { validate, validateAny, type Validator } from '../validation'
-import { EventManager } from '../events/event-manager'
 import { ContextConsumer } from './context-consumer'
-import { merge } from '../dataflow'
+import { cloneDeep } from 'lodash'
+
+export type AppScope = {}
+export type RequestScope = {}
+export type AppContext = Context<AppScope>
+export type RequestContext = Context<RequestScope>
 
 export type ContextMiddleware = (context: Context) => any | Promise<any>
-export type ContextState = Record<
-    PropertyKey,
-    ContextAttribute<StateValue<any>>
->
+export type ContextState<TContext extends Context> = Record<PropertyKey, ContextAttribute<TContext, StateValue<any>>>
 
 export type ContextResolver<T> = (context: Context) => StateValue<T>
 
 export type StateValue<T> = T
 
-export type ContextAttribute<T> = {
+export enum DependencyType {
+    VALUE = 'VALUE',
+    FACTORY = 'FACTORY',
+    CLASS = 'CLASS',
+}
+
+export type FactoryFn<T, A extends any[]> = (...args: A) => T
+export type ValueLoader<C extends Context, T> = (context: C) => T
+export type FilterKeysByType<TScope, TValue> = {
+    [Key in keyof TScope]: TScope[Key] extends TValue ? Key : never
+}[keyof TScope]
+export type FilterKeysByAsyncType<TScope, TValue> = {
+    [Key in keyof TScope]: TScope[Key] extends PromiseOrValue<TValue> ? Key : never
+}[keyof TScope]
+export type FilterArgsByType<TScope, TArgs extends any[]> = {
+    [Key in keyof TArgs]: FilterKeysByType<TScope, TArgs[Key]>
+}
+export type FilterAsyncArgsByType<TScope, TArgs extends any[]> = {
+    [Key in keyof TArgs]: FilterKeysByAsyncType<TScope, TArgs[Key]>
+}
+
+export type ContextAttribute<TContext extends Context<any>, TValue> = {
     key: PropertyKey
-    value?: T
+    value?: ValueLoader<TContext, TValue>
+    type: DependencyType
+    resolveOptions: ResolveOptions
+    cachedValue?: TValue
+    inject: PropertyKey[]
 }
 
-export type ContextListener = (context: Context, ...args: any[]) => any
+export type ScopeKey<S extends object> = keyof S
 
-export class Context {
-    private readonly state: ContextState = {}
+export type ContextListener = (context: Context) => any
+
+export type ResolveOptions = {
+    strict?: boolean
+    eager?: boolean
+    singleton?: boolean
+}
+
+export function defaultResolveOptions(): ResolveOptions {
+    return {
+        strict: false,
+        eager: false,
+        singleton: false,
+    }
+}
+
+export type ContextOptions = {
+    defaultResolveOptions?: ResolveOptions
+}
+
+export class Context<Scope extends object = any> {
+    private readonly state: ContextState<this> = {}
     private readonly emitter = new EventManager()
 
+    public readonly scope: Scope = {} as Scope
+
+    protected readonly defaultResolveOptions: ResolveOptions
+
+    constructor(options?: ContextOptions) {
+        this.defaultResolveOptions = {
+            ...defaultResolveOptions(),
+            ...options?.defaultResolveOptions,
+        }
+    }
+
     /**
      * Set a value in context, to be injected later.
      *
      * @param key
      * @param payload
+     * @deprecated Use `provideValue` instead, or you can register the same dependency as a factory with `provideFactory` or class with `provideClass`.
+     */
+    provide<K extends ScopeKey<Scope>>(key: K, payload: Scope[K]) {
+        const attribute: ContextAttribute<this, Scope[K]> = {
+            value: () => payload,
+            key,
+            type: DependencyType.VALUE,
+            resolveOptions: {
+                eager: false,
+                singleton: true,
+                strict: false,
+            },
+            inject: [],
+        }
+
+        this.state[key] = attribute
+    }
+
+    /**
+     * Manually register a dependency. This should normally be used by utils or integrations that need to register dependencies in creative ways. For normal use cases, using `provideValue`, `provideFactory`, or `provideClass` is sufficient.
+     *
+     * @param key The key to register the dependency under
+     * @param dep The dependency record
      */
-    provide<T>(key: PropertyKey, payload: StateValue<T>) {
-        let value: T | undefined = payload
+    register<K extends ScopeKey<Scope>>(key: K, dep: ContextAttribute<this, Scope[K]>) {
+        const existingDep = this.state[key]
+        this.state[key] = dep
+
+        Object.defineProperty(this.scope, key, {
+            get: () => this.resolve(key),
+            enumerable: true,
+            configurable: true,
+        })
 
-        const attribute: ContextAttribute<T> = {
-            value,
+        if (dep?.resolveOptions?.eager) {
+            this.on('declaro:init', async () => {
+                await this.resolve(key)
+            })
+        }
+
+        // kill any cached values that were made by a previous instance of this attribute
+        if (existingDep) {
+            const dependents = this.getAllDependents(key)
+
+            dependents.forEach((dependent) => {
+                dependent.cachedValue = undefined
+            })
+        }
+    }
+
+    /**
+     * Register a value in context scope.
+     *
+     * @param key The key to register the dependency under
+     * @param value The value to register
+     */
+    registerValue<K extends ScopeKey<Scope>>(key: K, value: Scope[K], defaultResolveOptions?: ResolveOptions) {
+        const attribute: ContextAttribute<this, Scope[K]> = {
+            value: () => value,
             key,
+            type: DependencyType.VALUE,
+            resolveOptions: defaultResolveOptions,
+            inject: [],
         }
 
-        this.state[key as any] = attribute
+        this.register(key, attribute)
+
+        return this
     }
 
     /**
-     * Extract a value from context.
+     * Register a dependency as a factory in context scope.
      *
-     * @param key
-     * @returns
+     * @param key The key to register the dependency under
+     * @param factory A factory function that will be called to generate the value when it is requested.
+     * @param inject An array of keys to use when injecting factory args.
+     * @returns A chainable instance of context
      */
-    inject<T = any>(key: PropertyKey): T | undefined {
-        const attribute = this.state[key as any]
+    registerFactory<K extends ScopeKey<Scope>, A extends any[]>(
+        key: K,
+        factory: FactoryFn<Scope[K], A>,
+        inject?: FilterArgsByType<Scope, A>,
+        defaultResolveOptions?: ResolveOptions,
+    ) {
+        const attribute: ContextAttribute<this, Scope[K]> = {
+            value: (context) => {
+                const args = (inject?.map((key) => context.resolve(key)) ?? []) as A
+
+                return factory(...args)
+            },
+            key,
+            type: DependencyType.FACTORY,
+            resolveOptions: defaultResolveOptions,
+            inject: inject ?? [],
+        }
+
+        this.register(key, attribute)
+
+        return this
+    }
+
+    registerAsyncFactory<K extends FilterKeysByType<Scope, Promise<any>>, A extends any[]>(
+        key: K,
+        factory: FactoryFn<Scope[K], A>,
+        inject?: FilterAsyncArgsByType<Scope, A>,
+        defaultResolveOptions?: ResolveOptions,
+    ) {
+        const attribute: ContextAttribute<this, Scope[K]> = {
+            value: (async (context) => {
+                const args = (await Promise.all((inject?.map((key) => context.resolve(key)) as A) ?? [])) as A
+
+                return await factory(...args)
+            }) as ValueLoader<this, Scope[K]>,
+            key,
+            type: DependencyType.FACTORY,
+            resolveOptions: defaultResolveOptions,
+            inject: inject ?? [],
+        }
+
+        this.register(key, attribute)
+
+        return this
+    }
+
+    registerClass<K extends FilterKeysByType<Scope, InstanceType<T>>, T extends Class<Scope[K]>>(
+        key: K,
+        Class: T,
+        inject?: FilterArgsByType<Scope, ConstructorParameters<T>>,
+        defaultResolveOptions?: ResolveOptions,
+    ) {
+        const attribute: ContextAttribute<this, Scope[K]> = {
+            value: (context) => {
+                const args = inject?.map((key) => context.resolve(key)) ?? []
+
+                return new (Class as any)(...(args as any))
+            },
+            key,
+            type: DependencyType.CLASS,
+            resolveOptions: defaultResolveOptions,
+            inject: inject ?? [],
+        }
+
+        this.register(key, attribute)
+
+        return this
+    }
+
+    registerAsyncClass<K extends FilterKeysByType<Scope, InstanceType<any>>, T extends Class<UnwrapPromise<Scope[K]>>>(
+        key: K,
+        Class: T,
+        inject?: FilterAsyncArgsByType<Scope, ConstructorParameters<T>>,
+        defaultResolveOptions?: ResolveOptions,
+    ) {
+        const attribute: ContextAttribute<this, Scope[K]> = {
+            value: (async (context) => {
+                const args = (await Promise.all(
+                    (inject?.map((key) => context.resolve(key)) ?? []) as ConstructorParameters<T>,
+                )) as ConstructorParameters<T>
+
+                return new (Class as any)(...(args as any))
+            }) as ValueLoader<this, Scope[K]>,
+            key,
+            type: DependencyType.CLASS,
+            resolveOptions: defaultResolveOptions,
+            inject: inject ?? [],
+        }
+
+        this.register(key, attribute)
+
+        return this
+    }
+
+    getAllDependencies<K extends ScopeKey<Scope>>(key: K): ContextAttribute<this, any>[] {
+        const attribute = this.state[key]
 
         if (!attribute) {
-            return undefined
+            return []
+        }
+        const dependencies =
+            attribute.inject?.map((key) => this.state[key] ?? ({ key } as ContextAttribute<typeof this, any>)) ?? []
+
+        attribute.inject?.forEach((key) => {
+            const nestedDependencies = this.getAllDependencies(key as any)
+            dependencies.push(...nestedDependencies)
+        })
+
+        return dependencies
+    }
+
+    getAllDependents<K extends ScopeKey<Scope>>(key: K): ContextAttribute<this, any>[] {
+        const dependents = Object.entries(this.state)
+            .filter(([_, attribute]) => attribute.inject?.includes(key))
+            .map(([key, attribute]) => attribute)
+
+        dependents.forEach((dependent) => {
+            const nestedDependents = this.getAllDependents(dependent.key as any)
+            dependents.push(...nestedDependents)
+        })
+
+        return dependents
+    }
+
+    introspect<K extends ScopeKey<Scope>>(key: K) {
+        const attribute = this.state[key]
+
+        return attribute
+    }
+
+    protected _cacheIsValid<K extends ScopeKey<Scope>>(key: K): boolean {
+        const attribute = this.state[key]
+
+        const needsCache = attribute.resolveOptions?.singleton || attribute.resolveOptions?.eager
+
+        if (!needsCache) {
+            return true
+        }
+
+        const hasCachedValue = attribute.cachedValue !== undefined && attribute.cachedValue !== null
+
+        if (!hasCachedValue) {
+            return false
+        }
+
+        return hasCachedValue && attribute.inject?.every((key) => this._cacheIsValid(key as any))
+    }
+
+    protected _resolveValue<K extends ScopeKey<Scope>>(key: K, resolveOptions?: ResolveOptions): Scope[K] {
+        const attribute = this.state[key]
+
+        const attributeResolveOptions = {
+            ...this.defaultResolveOptions,
+            ...attribute?.resolveOptions,
+            ...resolveOptions,
+        }
+
+        if (!attribute && attributeResolveOptions.strict) {
+            throw new Error(`Dependency ${key?.toString()} not found.`)
+        }
+
+        let value: Scope[K]
+
+        const serveFromCache = attributeResolveOptions.singleton || attributeResolveOptions.eager
+        const dependenciesValid = attribute?.inject?.every((key) => this._cacheIsValid(key as any))
+
+        if (serveFromCache && attribute?.cachedValue && dependenciesValid) {
+            value = attribute.cachedValue
+        } else {
+            value = attribute?.value(this)
+        }
+
+        if (serveFromCache) {
+            attribute.cachedValue = value
+        }
+
+        if (attributeResolveOptions.strict && (value === undefined || value === null)) {
+            throw new Error(`Strict dependency ${key?.toString()} has a ${typeof value} value.`)
         }
 
-        return attribute.value
+        return value
+    }
+
+    /**
+     * Extract a value from context.
+     *
+     * @param key
+     * @returns
+     * @deprecated Use `resolve` instead
+     */
+    inject<T = any>(key: ScopeKey<Scope>): T | undefined {
+        return this._resolveValue(key) as T
+    }
+
+    resolve<K extends ScopeKey<Scope>>(key: K, resolveOptions?: ResolveOptions): Scope[K] {
+        return this._resolveValue(key, resolveOptions)
     }
 
     /**
@@ -63,10 +370,10 @@ export class Context {
      * @param key
      * @param instance
      */
-    singleton<T = any>(key: PropertyKey, instance: T) {
+    singleton<T = any>(key: ScopeKey<Scope>, instance: T) {
         const existing = this.inject<T>(key)
         if (!existing) {
-            this.provide(key, instance)
+            this.provide(key, instance as any)
             return instance
         } else {
             return existing
@@ -92,10 +399,15 @@ export class Context {
      * @param contexts
      * @returns
      */
-    extend(...contexts: Context[]) {
-        return contexts.reduce((workingState, context) => {
-            return merge(workingState, context.state)
-        }, this.state)
+    extend(...contexts: Context[]): this {
+        contexts.forEach((context) => {
+            Reflect.ownKeys(context.state).forEach((key) => {
+                const dep = cloneDeep(context.state[key])
+                this.register(key as any, dep)
+            })
+        })
+
+        return this
     }
 
     /**
@@ -138,7 +450,9 @@ export class Context {
      * @returns
      */
     on(event: string, listener: ContextListener) {
-        return this.emitter.on(event, listener)
+        return this.emitter.on(event, (_) => {
+            return listener(this)
+        })
     }
 
     /**
@@ -148,7 +462,9 @@ export class Context {
      * @param args
      * @returns
      */
-    async emit(event: string, ...args: any[]) {
-        return await this.emitter.emitAsync(event, this, ...args)
+    async emit(event: string) {
+        return await this.emitter.emitAsync({
+            type: event,
+        })
     }
 }

package/src/context/legacy-context.test.ts

@@ -0,0 +1,141 @@
+import { Context } from './context'
+import { sleep } from '../timing'
+import { ContextConsumer } from './context-consumer'
+import { describe, it, vi } from 'vitest'
+
+describe('Context', () => {
+    it('Should allow simple value dependency injection', async ({ expect }) => {
+        const context = new Context()
+
+        context.provide('test', 'Hello World')
+
+        const message = context.inject('test')
+
+        expect(message).toBe('Hello World')
+
+        const TEST_KEY = Symbol()
+        context.provide(TEST_KEY, 42)
+
+        const number = context.inject(TEST_KEY)
+        expect(number).toBe(42)
+    })
+
+    it('Should allow subscription to arbitrary events', async ({ expect }) => {
+        const customEventCall = vi.fn()
+
+        const context = new Context()
+        context.provide('test', 'Hello World')
+        expect(customEventCall.mock.calls.length).toBe(0)
+
+        context.on('customEvent', async (ctx) => {
+            customEventCall()
+            const message = await ctx.inject('test')
+            expect(message).toBe('Hello World')
+        })
+
+        await context.emit('customEvent')
+
+        expect(customEventCall.mock.calls.length).toBe(1)
+    })
+
+    it('Should extend other contexts', async ({ expect }) => {
+        const context1 = new Context()
+        const context2 = new Context()
+        const context3 = new Context()
+
+        const SYMBOL_KEY = Symbol()
+
+        context1.provide('a', 1)
+        context1.provide('c', 1)
+        context2.provide('b', 2)
+        context2.provide('c', 2)
+        context2.provide(SYMBOL_KEY, 42)
+        context3.provide('c', 3)
+
+        context1.extend(context2, context3)
+
+        const a = context1.inject('a')
+        const b = context1.inject('b')
+        const c = context1.inject('c')
+        const symbolValue = context1.inject(SYMBOL_KEY)
+
+        expect(a).toBe(1)
+        expect(b).toBe(2)
+        expect(c).toBe(3)
+        expect(symbolValue).toBe(42)
+    })
+
+    it('Should nest contexts', async ({ expect }) => {
+        const context1 = new Context()
+        const context2 = new Context()
+
+        context1.provide('a', 1)
+        context2.provide('a', 2)
+
+        context1.provide('nested', context2)
+
+        const a1 = context1.inject('a')
+        const a2 = context1.inject<Context>('nested')?.inject('a')
+
+        expect(a1).toBe(1)
+        expect(a2).toBe(2)
+    })
+
+    it('Should allow async middleware', async ({ expect }) => {
+        const context = new Context()
+
+        await context.use(async (context) => {
+            context.provide('TEST1', 'Hello World')
+            await sleep(1)
+            context.provide('TEST2', 'Hello Test')
+        })
+
+        const test1 = context.inject('TEST1')
+        const test2 = context.inject('TEST2')
+        expect(test1).toBe('Hello World')
+        expect(test2).toBe('Hello Test')
+    })
+
+    it('Should allow singletons', ({ expect }) => {
+        const context = new Context()
+
+        const KEY = Symbol()
+        let instance = context.singleton(KEY, 1)
+        instance = context.singleton(KEY, 2)
+        instance = context.singleton(KEY, 3)
+
+        expect(instance).toBe(1)
+    })
+
+    it('Should allow hydration', ({ expect }) => {
+        const context = new Context()
+
+        class Test extends ContextConsumer {
+            constructor(public context: Context) {
+                super(context)
+            }
+
+            test() {
+                return 'Yes'
+            }
+        }
+
+        expect(context.hydrate(Test).test()).toBe('Yes')
+    })
+
+    it('Should allow hydration with args', ({ expect }) => {
+        const context = new Context()
+
+        class Test extends ContextConsumer {
+            constructor(public context: Context, foo: string, bar: number) {
+                super(context)
+            }
+
+            test() {
+                return 'Yes'
+            }
+        }
+
+        expect(context.hydrate(Test, 'hello', 42).test()).toBe('Yes')
+    })
+})

package/src/errors/errors.ts

@@ -0,0 +1,73 @@
+export interface IError {
+    code: number
+    message: string
+    meta: any
+}
+
+export abstract class BaseError extends Error implements IError {
+    public readonly meta: any
+    public readonly code: number = 500
+
+    constructor(message: string, meta?: any) {
+        super(message)
+        this.name = 'BaseError'
+        this.meta = meta
+    }
+
+    public toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            meta: this.meta,
+        }
+    }
+
+    public toString() {
+        return JSON.stringify(this.toJSON())
+    }
+}
+
+export class SystemError extends BaseError {
+    public readonly code: number = 500
+
+    constructor(message: string, meta?: any) {
+        super(message, meta)
+        this.name = 'SystemError'
+    }
+}
+
+export class ValidationError extends BaseError {
+    public readonly code: number = 400
+
+    constructor(message: string, meta?: any) {
+        super(message, meta)
+        this.name = 'ValidationError'
+    }
+}
+
+export class NotFoundError extends BaseError {
+    public readonly code: number = 404
+
+    constructor(message: string, meta?: any) {
+        super(message, meta)
+        this.name = 'NotFoundError'
+    }
+}
+
+export class UnauthorizedError extends BaseError {
+    public readonly code: number = 401
+
+    constructor(message: string, meta?: any) {
+        super(message, meta)
+        this.name = 'UnauthorizedError'
+    }
+}
+
+export class ForbiddenError extends BaseError {
+    public readonly code: number = 403
+
+    constructor(message: string, meta?: any) {
+        super(message, meta)
+        this.name = 'ForbiddenError'
+    }
+}