@typetron/framework 0.5.20 → 0.5.22

package/.automaker/features/webhook-notifications/feature.json

@@ -0,0 +1,14 @@
+{
+  "id": "webhook-notifications",
+  "category": "Notifications",
+  "title": "Webhook Notifications",
+  "description": "Implement webhook delivery for notifications sent to external services. Supports webhook retry logic, signature verification, and payload transformation.",
+  "status": "backlog",
+  "priority": 2,
+  "complexity": "moderate",
+  "dependencies": [
+    "discord-notifications-channel"
+  ],
+  "createdAt": "2025-12-21T22:11:28.282Z",
+  "updatedAt": "2025-12-21T22:11:28.282Z"
+}

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run build:*)",
+      "Bash(npm ls:*)",
+      "Bash(npx tsc-alias:*)",
+      "Bash(npm uninstall:*)"
+    ]
+  }
+}

package/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+max_line_length = 140
+tab_width = 4
+trim_trailing_whitespace = true

package/.mocharc.json

@@ -0,0 +1,13 @@
+{
+	"extension": [
+		"ts"
+	],
+	"require": [
+		"tsconfig-paths/register",
+		"ts-node/register",
+		"source-map-support/register",
+		"reflect-metadata",
+		"./Support"
+	],
+	"spec": "tests/**/*Test.ts"
+}

package/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+_In progress_
+
+----
+
+Publishing:
+
+```
+cp Readme.md dist/Readme.md && cp package.json dist/package.json && cp package-lock.json dist/package-lock.json && cd dist && npm publish
+```

package/Cache/Cache.ts

@@ -0,0 +1,13 @@
+export abstract class Cache {
+    abstract has(name: string): Promise<boolean>
+
+    abstract get<T>(name: string, defaultValue?: T | (() => T | Promise<T>)): Promise<T | undefined>
+
+    abstract remember<T>(name: string, defaultValue?: T | (() => T | Promise<T>), duration?: number): Promise<T | undefined>
+
+    abstract set(name: string, data: any, duration?: number): Promise<void>
+
+    abstract delete(name: string): Promise<void>
+
+    abstract flush(): Promise<void>
+}

package/Cache/Stores/DatabaseStore.ts

@@ -0,0 +1,120 @@
+import { Cache } from '@Typetron/Cache'
+import { Query } from '@Typetron/Database'
+import { JSONSafeParse } from '@Typetron/Support/utils'
+import { CacheItem } from '@Typetron/Cache/types'
+import { createHash } from 'crypto'
+import { Create } from '@Typetron/Database/Drivers/SQLite/Create'
+
+export class DatabaseStore extends Cache {
+    constructor(public table: string) {
+        super()
+    }
+
+    private get cacheTable() {
+        return new Query<CacheItem<unknown>>().table(this.table)
+    }
+
+    private getNameHash(name: string) {
+        return createHash('sha1').update(name).digest('hex')
+    }
+
+    async has(name: string): Promise<boolean> {
+        const row = await this.cacheTable.where('name', this.getNameHash(name)).first()
+        return !!row
+    }
+
+    async get<T>(name: string, defaultValue?: T | (() => T | Promise<T>)): Promise<T | undefined> {
+        if (!await Query.connection.driver.tableExists(this.table)) {
+            return undefined
+        }
+
+        const row = await this.cacheTable.where('name', this.getNameHash(name)).first()
+
+        if (!row) {
+            return this.getDefaultValue(defaultValue)
+        }
+
+        const currentTime = Date.now()
+
+        if (row.date && row.date < currentTime) {
+            await this.delete(name)
+            return this.getDefaultValue(defaultValue)
+        }
+
+        return JSONSafeParse<T>(String(row.value))
+    }
+
+    async remember<T>(name: string, defaultValue?: T | (() => T | Promise<T>), durationInSeconds?: number): Promise<T | undefined> {
+        const value = await this.get<T>(name)
+
+        if (!value) {
+            const newValue = await this.getDefaultValue(defaultValue)
+            await this.set(name, newValue, durationInSeconds)
+            return newValue
+        }
+
+        return value
+    }
+
+    async set(name: string, value: any, durationInSeconds?: number): Promise<void> {
+        await this.makeSureTheTableExists()
+        const expirationTime = durationInSeconds ? Date.now() + durationInSeconds * 1000 : undefined
+        const serializedValue = JSON.stringify(value)
+
+        const existing = await this.cacheTable.where('name', this.getNameHash(name)).first()
+
+        if (existing) {
+            await this.cacheTable.where('name', this.getNameHash(name)).update({
+                value: serializedValue,
+                date: expirationTime
+            })
+        } else {
+            await this.cacheTable.insert({
+                name: this.getNameHash(name),
+                value: serializedValue,
+                date: expirationTime
+            })
+        }
+    }
+
+    async delete(name: string): Promise<void> {
+        await this.cacheTable.where('name', this.getNameHash(name)).delete()
+    }
+
+    async flush(): Promise<void> {
+        await this.cacheTable.delete()
+    }
+
+    private async getDefaultValue<T>(defaultValue?: (() => (Promise<T> | T)) | T) {
+        const valueFunction = typeof defaultValue === 'function'
+            ? defaultValue as () => Promise<T> | T
+            : () => defaultValue
+
+        return valueFunction()
+    }
+
+    private async makeSureTheTableExists() {
+        if (!await Query.connection.driver.tableExists(this.table)) {
+            const createStatement = new Create(this.table, [
+                {
+                    name: 'name',
+                    type: 'string',
+                    primaryKey: true,
+                    nullable: true,
+                },
+                {
+                    name: 'value',
+                    type: 'string',
+                    nullable: true,
+                },
+                {
+                    name: 'date',
+                    type: 'integer',
+                    nullable: true,
+                },
+            ])
+
+            await Query.connection.driver.run(createStatement.toSQL())
+        }
+    }
+}

package/Cache/Stores/FileStore.ts

@@ -0,0 +1,69 @@
+import { Cache } from '@Typetron/Cache'
+import { Storage } from '@Typetron/Storage'
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { JSONSafeParse } from '@Typetron/Support/utils'
+import { CacheItem } from '@Typetron/Cache/types'
+
+export class FileStore extends Cache {
+    constructor(public storage: Storage, public directory: string) {
+        super()
+    }
+
+    async has(name: string): Promise<boolean> {
+        return await this.storage.exists(this.path(name))
+    }
+
+    async get<T>(name: string, defaultValue?: T | (() => T | Promise<T>)): Promise<T | undefined> {
+        const item: CacheItem<T> = await this.storage.read(this.path(name))
+            .then(async (data) => JSONSafeParse<CacheItem<T>>(data.toString()) ?? {value: await this.getDefaultValue<T>(defaultValue)})
+            .catch(async () => ({value: await this.getDefaultValue<T>(defaultValue)}))
+
+        if (item['date'] && item['date'] < new Date().getTime()) {
+            await this.delete(name)
+            return this.getDefaultValue(defaultValue)
+        }
+
+        return item['value']
+    }
+
+    async remember<T>(name: string, defaultValue?: T | (() => T | Promise<T>), durationInSeconds?: number): Promise<T | undefined> {
+        const data = await this.get<T>(name)
+
+        if (data !== undefined) {
+            return data
+        }
+
+        const value = await this.getDefaultValue(defaultValue)
+        await this.set(name, value, durationInSeconds)
+        return value
+    }
+
+    async set(name: string, value: any, durationInSeconds?: number): Promise<void> {
+        await this.storage.put(this.path(name), JSON.stringify({
+            value,
+            date: durationInSeconds ? Date.now() + durationInSeconds * 1000 : undefined
+        } as CacheItem<unknown>))
+    }
+
+    async delete(name: string): Promise<void> {
+        await this.storage.delete(this.path(name))
+    }
+
+    async flush(): Promise<void> {
+        await this.storage.deleteDirectory(this.directory)
+    }
+
+    private path(key: string): string {
+        const hashKey = createHash('sha1').update(key).digest('hex')
+        return path.join(this.directory, '/', hashKey)
+    }
+
+    private async getDefaultValue<T>(defaultValue?: (() => (Promise<T> | T)) | T) {
+        const valueFunction = typeof defaultValue === 'function'
+            ? defaultValue as () => Promise<T> | T
+            : () => defaultValue
+
+        return valueFunction()
+    }
+}

package/Cache/Stores/MemoryStore.ts

@@ -0,0 +1,71 @@
+import { Cache } from '@Typetron/Cache'
+import { CacheItem } from '@Typetron/Cache/types'
+
+export class MemoryStore extends Cache {
+    public cache: Map<string, CacheItem<unknown>> = new Map()
+
+    async has(name: string): Promise<boolean> {
+        const cacheItem = this.cache.get(name)
+
+        if (!cacheItem) {
+            return false
+        }
+
+        const currentTime = Date.now()
+
+        if (cacheItem.date && cacheItem.date < currentTime) {
+            this.cache.delete(name)
+            return false
+        }
+
+        return true
+    }
+
+    async get<T>(name: string, defaultValue?: T | (() => T | Promise<T>)): Promise<T | undefined> {
+        const cacheItem = this.cache.get(name)
+
+        if (!await this.has(name)) {
+            return this.getDefaultValue(defaultValue)
+        }
+
+        return cacheItem!.value as T
+    }
+
+    // return (cacheItem as CacheItem<T>).value as T
+    async remember<T>(name: string, defaultValue?: T | (() => T | Promise<T>), durationInSeconds?: number): Promise<T | undefined> {
+        const cacheItem = this.cache.get(name)
+
+        if (await this.has(name)) {
+            return cacheItem!.value as T
+        }
+
+        const value = await this.getDefaultValue(defaultValue)
+        await this.set(name, value, durationInSeconds)
+        return value
+    }
+
+    async set(name: string, value: any, durationInSeconds?: number): Promise<void> {
+        const expirationTime = durationInSeconds ? Date.now() + durationInSeconds * 1000 : Infinity
+
+        this.cache.set(name, {
+            value: value,
+            date: expirationTime
+        })
+    }
+
+    async delete(name: string): Promise<void> {
+        this.cache.delete(name)
+    }
+
+    async flush(): Promise<void> {
+        this.cache.clear()
+    }
+
+    private async getDefaultValue<T>(defaultValue?: (() => (Promise<T> | T)) | T) {
+        const valueFunction = typeof defaultValue === 'function'
+            ? defaultValue as () => Promise<T> | T
+            : () => defaultValue
+
+        return valueFunction()
+    }
+}

package/Cache/index.ts

@@ -0,0 +1,5 @@
+export * from './types'
+export * from './Cache'
+export * from './Stores/MemoryStore'
+export * from './Stores/FileStore'
+export * from './Stores/DatabaseStore'

package/Cache/types.ts

@@ -0,0 +1,4 @@
+export interface CacheItem<T>{
+    value?: T
+    date?: number
+}

package/Container/ClassResolver.ts

@@ -0,0 +1,106 @@
+import { Constructor } from '../Support'
+import { BaseResolver } from './Resolver'
+import { InjectableMetadata, Scope } from './Metadata'
+import { Container } from './Container'
+import { ParametersTypesMetadata } from '@Typetron/Support/Metadata'
+
+export class ClassResolver extends BaseResolver {
+    canResolve<T>(abstract: Constructor<T>): boolean {
+        return abstract.prototype && abstract.prototype.constructor.name
+    }
+
+    resolve<T>(abstract: Constructor<T>, parametersValues: object[]) {
+
+        // TODO improve this since it looks very hard to write next time
+        const parametersTypes: Constructor[] = ParametersTypesMetadata.get(abstract).parameters
+            ?? (ParametersTypesMetadata.get(abstract).parameters = Reflect.getMetadata('design:paramtypes', abstract) ?? [])
+
+        const parameters = parametersTypes.map((parameterType, index) => {
+            if (parametersValues[index]) {
+                return parametersValues[index]
+            }
+            if (parameterType.name === 'Object' && parametersValues[index]) {
+                parameterType = parametersValues[index] as Constructor // || this.getParameterValue(abstract, index);
+            }
+            return this.container.get(parameterType)
+        })
+
+        const instance = new abstract(...parameters)
+
+        const metadata = InjectableMetadata.get(abstract)
+        let asyncDependencies = 0
+        let resolve: (value: T | PromiseLike<T>) => void
+        let reject: (reason?: unknown) => void
+        for (const dependency in metadata.dependencies) {
+            const dependencyAbstract = metadata.dependencies[dependency]
+            if (!dependencyAbstract) {
+                continue
+            }
+            const value = this.container.get(dependencyAbstract) as T[keyof T]
+            if (value instanceof Promise) {
+                asyncDependencies++
+                value
+                    .then((resolvedValue) => {
+                        instance[dependency as keyof T] = resolvedValue
+                        asyncDependencies--
+                        if (!asyncDependencies) {
+                            resolve(instance)
+                        }
+                    })
+                    .catch((error) => {
+                        reject(error)
+                    })
+            } else {
+                instance[dependency as keyof T] = value
+            }
+        }
+        if (asyncDependencies) {
+            return new Promise<T>((resolveFunction, rejectFunction) => {
+                resolve = resolveFunction
+                reject = rejectFunction
+            })
+        }
+
+        return instance
+    }
+
+    // TODO figure out how to use this better
+    // private getParameterValue<T>(abstract: Constructor<T>, index: number) {
+    //     const injectMetadata = Reflect.getMetadata('container:inject', abstract);
+    //     if (!injectMetadata) {
+    //         throw new Error(`No binding found for parameter ${index} in '${abstract.name}'`);
+    //     }
+    //     const value = injectMetadata.find((metadata: any) => metadata.index === index);
+    //     return value.abstract;
+    // }
+
+    reload<T>(
+        abstract: Constructor<T>,
+        concrete: T,
+        container: Container = this.container
+    ): T {
+        const metadata = InjectableMetadata.get(abstract)
+        for (const dependencyName in metadata.dependencies) {
+            if (!metadata.dependencies[dependencyName]) {
+                continue
+            }
+            const dependency = metadata.dependencies[dependencyName]
+            if (!dependency) {
+                continue
+            }
+            if (typeof dependency === 'symbol') {
+                concrete[dependencyName as keyof T] = container.get(
+                    dependency
+                ) as T[keyof T]
+                continue
+            }
+            const dependencyMetadata = InjectableMetadata.get(dependency)
+            if (dependencyMetadata.scope === Scope.REQUEST) {
+                concrete[dependencyName as keyof T] = container.get(
+                    dependency
+                ) as T[keyof T]
+            }
+        }
+        return concrete
+    }
+}

package/Container/Container.ts

@@ -0,0 +1,144 @@
+import { Constructor, Type } from '../Support'
+import { ClassResolver } from './ClassResolver'
+import { ServiceIdentifier } from './Contracts'
+import { InjectableMetadata, Scope } from './Metadata'
+import { Resolver } from './Resolver'
+
+export class Container {
+    protected static instance: Container
+
+    // TODO performance: get rid of this
+    public resolvers: Resolver[] = [
+        new ClassResolver(this)
+    ]
+
+    // tslint:disable-next-line:no-any
+    protected instances = new Map<ServiceIdentifier<any>, any>()
+
+    public parent?: Container
+
+    static getInstance() {
+        if (!Container.instance) {
+            Container.instance = new Container()
+        }
+
+        return Container.instance
+    }
+
+    static setInstance(container: Container) {
+        return Container.instance = container
+    }
+
+    getInstances() {
+        return this.instances
+    }
+
+    set<T>(abstract: ServiceIdentifier<T>, concrete: T | Type<T> | (() => void)) {
+        this.instances.set(abstract, concrete)
+    }
+
+    /**
+     * @deprecated
+     */
+    forceSet<T>(abstract: ServiceIdentifier<T>, concrete: T | Type<T> | (() => any)) {
+        this.set(abstract, concrete)
+    }
+
+    // tslint:disable-next-line:no-any
+    get<T>(abstract: ServiceIdentifier<T>, parameters: any[] = []): T {
+        const metadata = this.getMetadata(abstract)
+
+        if (metadata.scope === Scope.TRANSIENT) {
+            return this.getResolver(abstract, metadata).resolve(abstract, parameters) as T
+        }
+
+        let concrete = this.getInstance(abstract)
+        if (concrete) {
+            return concrete
+        }
+
+        // if (this.parent && metadata.scope !== Scope.REQUEST
+        //     && (concrete = this.parent.getInstance(abstract) ?? this.parent.get(abstract))
+        // ) {
+        //     return concrete
+        // }
+
+        if (this.parent && metadata.scope !== Scope.REQUEST && (concrete = this.parent.getInstance(abstract))) {
+            return concrete
+        }
+
+        if (typeof abstract === 'string') {
+            const instance = this.getInstance<T>(abstract) as T
+            if (!instance) {
+                throw new Error(`No instance found for '${this.getAbstractName(abstract)}'`)
+            }
+        }
+
+        const resolver = this.getResolver(abstract, metadata)
+        concrete = resolver.resolve(abstract, parameters) as T
+        this.set(abstract, concrete)
+        return concrete
+    }
+
+    createChildContainer(): Container {
+        const childContainer = new Container()
+        childContainer.parent = this
+        childContainer.set(Container, childContainer)
+        // TODO performance: get rid of this
+        childContainer.resolvers = this.resolvers.map(resolver => {
+            return new (resolver.constructor as Constructor<Resolver>)(childContainer)
+        })
+        return childContainer
+    }
+
+    private getMetadata<T>(abstract: ServiceIdentifier<T>) {
+        if (abstract instanceof Object) {
+            return InjectableMetadata.get(abstract)
+        }
+        return new InjectableMetadata
+    }
+
+    private getAbstractName<T>(abstract: ServiceIdentifier<T>): string {
+        if (typeof abstract === 'string') {
+            return abstract
+        }
+        if (abstract === undefined) {
+            throw new Error(`
+                Cannot resolve a parameter having the value undefined.
+                This might be due to circular dependencies in your app
+            `)
+        }
+        if (typeof abstract === 'symbol') {
+            return abstract.toString()
+        }
+        if ('name' in abstract) {
+            return abstract.name
+        }
+        throw new Error(`Cannot get abstract name for ${abstract}`)
+    }
+
+    private getResolver<T>(abstract: ServiceIdentifier<T>, metadata: InjectableMetadata) {
+        let resolver = metadata.resolver
+        if (!resolver) {
+            resolver = this.resolvers.find(item => item.canResolve(abstract))
+        }
+        if (!resolver) {
+            throw new Error(`Resolver not found for '${this.getAbstractName(abstract)}'`)
+        }
+        this.setResolverForAbstract(abstract, resolver, metadata)
+        resolver.container = this
+        return resolver
+    }
+
+    private setResolverForAbstract<T>(abstract: ServiceIdentifier<T>, resolver: Resolver, metadata: InjectableMetadata) {
+        if (typeof abstract === 'symbol') {
+            return
+        }
+        metadata.resolver = resolver
+        InjectableMetadata.set(metadata, abstract)
+    }
+
+    private getInstance<T>(abstract: ServiceIdentifier<T>): T | undefined {
+        return this.instances.get(abstract) || this.parent?.getInstance(abstract)
+    }
+}

package/Container/Contracts.ts

@@ -0,0 +1,3 @@
+import { Abstract, Constructor } from '../Support'
+
+export type ServiceIdentifier<T> = string | Constructor<T> | Abstract<T> | symbol;

package/Container/Decorators.ts

@@ -0,0 +1,20 @@
+import { ServiceIdentifier } from './Contracts'
+import { InjectableMetadata, Scope } from './Metadata'
+
+export function Injectable(scope: Scope = Scope.SINGLETON) {
+    return function <T extends Function>(target: T) {
+        const metadata = InjectableMetadata.get(target)
+        metadata.scope = scope
+        InjectableMetadata.set(metadata, target)
+    }
+}
+
+export function Inject<T extends Object>(abstract?: ServiceIdentifier<T>) {
+    return function (target: T, targetKey: string, index?: number) {
+        const fieldType = Reflect.getMetadata('design:type', target, targetKey) as ServiceIdentifier<T>
+        const metadata = InjectableMetadata.get(target.constructor)
+        metadata.dependencies[targetKey] = abstract ?? fieldType
+        InjectableMetadata.set(metadata, target.constructor)
+    }
+}
+

package/Container/Metadata.ts

@@ -0,0 +1,16 @@
+import { Resolver } from './Resolver'
+import { ServiceIdentifier } from './Contracts'
+import { MetadataKey } from '../Support/Metadata'
+
+export enum Scope {
+    TRANSIENT = 'TRANSIENT',
+    SINGLETON = 'SINGLETON',
+    REQUEST = 'REQUEST',
+}
+
+export class InjectableMetadata extends MetadataKey('injectable') {
+    resolver?: Resolver
+
+    scope: Scope = Scope.SINGLETON
+    dependencies: {[key: string]: ServiceIdentifier<{}>} = {}
+}

package/Container/Resolver.ts

@@ -0,0 +1,27 @@
+import { Container } from './Container'
+import { ServiceIdentifier } from './Contracts'
+
+export interface Resolver {
+    container: Container;
+
+    canResolve<T>(abstract: ServiceIdentifier<T>): boolean;
+
+    resolve<T>(abstract: ServiceIdentifier<T>, parameters: object[]): T | Promise<T>;
+
+    reload<T>(abstract: ServiceIdentifier<T>, concrete: T, container?: Container): T;
+}
+
+export abstract class BaseResolver implements Resolver {
+    constructor(public container: Container) {}
+
+    abstract canResolve<T>(abstract: ServiceIdentifier<T>): boolean;
+
+    abstract resolve<T>(abstract: ServiceIdentifier<T>, parameters: object[]): T | Promise<T>;
+
+    /**
+     * Used to update the dependencies that have the REQUEST scope
+     */
+    reload<T>(abstract: ServiceIdentifier<T>, concrete: T, container?: Container): T {
+        return concrete
+    }
+}

package/Container/index.ts

@@ -0,0 +1,5 @@
+export * from './Decorators'
+export * from './Container'
+export * from './ClassResolver'
+export * from './Resolver'
+export * from './Metadata'