feat(website): optimized API and new simpler website design/documentation

Author: marcj

.github/workflows/main.yml

@@ -22,6 +22,11 @@ jobs:
           SFTP_USERS: user:123:::upload
         ports:
           - '2222:22'
+      redis:
+        image: redis:7.0.11
+        ports:
+          - '6379:6379'
+        options: --health-cmd "redis-cli ping" --health-interval 10s --health-timeout 5s --health-retries 5
     steps:
       - uses: actions/checkout@v4
 
@@ -35,10 +40,12 @@ jobs:
             packages/api-console-module/tsconfig.json \
             packages/angular-ssr/tsconfig.json \
             packages/broker/tsconfig.json \
+            packages/broker-redis/tsconfig.json \
             packages/bson/tsconfig.json \
             packages/core/tsconfig.json \
             packages/core-rxjs/tsconfig.json \
             packages/filesystem/tsconfig.json \
+            packages/filesystem-database/tsconfig.json \
             packages/framework/tsconfig.json \
             packages/framework-debug-api/tsconfig.json \
             packages/framework-integration/tsconfig.json \
@@ -60,10 +67,12 @@ jobs:
         run: |
           npm run test:coverage \
             packages/broker/ \
+            packages/broker-redis/ \
             packages/bson/ \
             packages/core/ \
             packages/core-rxjs/ \
             packages/filesystem/ \
+            packages/filesystem-database/ \
             packages/framework/ \
             packages/framework-debug-api/ \
             packages/framework-integration/ \

package.json

@@ -17,7 +17,7 @@
     "clean": "find packages/*/dist/* ! -name 'package.json' -type f -exec rm -f {} +; rm -rf packages/*/.angular; rm -rf website/.angular; npm run postinstall",
     "clean:modules": "rm -rf packages/*/node_modules; rm -rf node_modules",
     "clean:lock": "rm -rf packages/*/package-lock.json; rm -rf package-lock.json",
-    "docs": "rm -rf docs && node --max-old-space-size=12096 node_modules/.bin/typedoc packages/*/index.ts",
+    "docs": "rm -rf docs && node --max-old-space-size=12096 node_modules/.bin/typedoc --options typedoc.js packages/*/index.ts",
     "publish": "lerna publish --no-private patch",
     "publish-force": "npm run build && lerna publish --no-private --force-publish",
     "check:circular": "madge --extensions ts --warning --circular",

packages/angular-ssr/src/angular.ts

@@ -14,8 +14,8 @@ import { eventDispatcher } from '@deepkit/event';
 import { createModuleClass } from '@deepkit/app';
 import { ApplicationServer } from '@deepkit/framework';
 import { Logger } from '@deepkit/logger';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 
 class AngularConfig {
     /**

packages/api-console-gui/src/app/components/inputs/date-input.component.ts

@@ -8,7 +8,7 @@ import { TypeDecoration } from '../../utils.js';
 @Component({
     template: `
       <dui-input round lightFocus type="datetime-local" style="width: 100%"
-                 (keyDown)="keyDown.emit($event)"
+                 (keydown)="keyDown.emit($event)"
                  [(ngModel)]="model().value" />
     `,
     imports: [

packages/api-console-gui/src/app/components/inputs/string-input.component.ts

@@ -8,7 +8,7 @@ import { FormsModule } from '@angular/forms';
 @Component({
     template: `
       <dui-input lightFocus [type]="getType()" style="width: 100%"
-                 (keyDown)="keyDown.emit($event)"
+                 (keydown)="keyDown.emit($event)"
                  [placeholder]="placeholder()"
                  [(ngModel)]="model().value"
       ></dui-input>

packages/app/src/app.ts

@@ -13,19 +13,14 @@ import { ConfigLoader, ServiceContainer } from './service-container.js';
 import { ConfigureProviderOptions, injectedFunction, InjectorContext, ResolveToken, Scope, Token } from '@deepkit/injector';
 import { AppModule, RootModuleDefinition } from './module.js';
 import { EnvConfiguration } from './configuration.js';
-import {
-    DataEventToken,
-    DispatchArguments,
-    EventDispatcher,
-    EventDispatcherDispatchType,
-    EventListener,
-    EventListenerCallback,
-    EventToken,
-} from '@deepkit/event';
+import { DataEventToken, DispatchArguments, EventDispatcher, EventDispatcherDispatchType, EventListener, EventListenerCallback, EventToken } from '@deepkit/event';
 import { ReceiveType, ReflectionClass, ReflectionKind } from '@deepkit/type';
 import { Logger } from '@deepkit/logger';
 import { executeCommand, getArgsFromEnvironment, getBinFromEnvironment } from './command.js';
 
+/**
+ * @internal
+ */
 export function setPartialConfig(target: { [name: string]: any }, partial: {
     [name: string]: any
 }, incomingPath: string = '') {
@@ -160,10 +155,13 @@ class EnvConfigLoader {
     }
 }
 
+/**
+ * @internal
+ */
 export class RootAppModule<T extends RootModuleDefinition> extends AppModule<T> {
 }
 
-export interface AppEvent {
+interface AppEvent {
     /**
      * The command that is about to be executed.
      */
@@ -177,12 +175,12 @@ export interface AppEvent {
     injector: InjectorContext;
 }
 
-export interface AppExecutedEvent extends AppEvent {
+interface AppExecutedEvent extends AppEvent {
     exitCode: number;
 }
 
 
-export interface AppErrorEvent extends AppEvent {
+interface AppErrorEvent extends AppEvent {
     error: Error;
 }
 
@@ -211,13 +209,10 @@ export const onAppError = new DataEventToken<AppErrorEvent>('app.error');
 export const onAppShutdown = new DataEventToken<AppEvent>('app.shutdown');
 
 /**
- * This is the smallest available application abstraction in Deepkit.
- *
- * It is based on a module and executes registered CLI controllers in `execute`.
- *
- * @deepkit/framework extends that with a more powerful Application class, that contains also HTTP and RPC controllers.
+ * This is the application abstraction in Deepkit.
  *
- * You can use this class for more integrated unit-tests.
+ * It is based on a module (the root module)
+ * and executes registered CLI controllers in `execute`.
  */
 export class App<T extends RootModuleDefinition> {
     protected envConfigLoader?: EnvConfigLoader;

packages/app/src/command.ts

@@ -71,11 +71,6 @@ export interface Command {
     execute(...args: any[]): Promise<number | void> | number | void;
 }
 
-export function isCommand(classType: ClassType<Command>) {
-    return !!cli._fetch(classType);
-}
-
-
 function convert(parameter: CommandParameter, value: any) {
     if (value === undefined) {
         if (parameter.optional) return undefined;
@@ -215,6 +210,9 @@ function getSpacing(names: string[]): number {
     return names.reduce((max, name) => Math.max(max, name.length), 0) + 1;
 }
 
+/**
+ * @internal
+ */
 export interface ParsedCliControllerConfig {
     controller?: ClassType,
     callback?: Function;
@@ -241,7 +239,7 @@ function commandNameFromSymbol(symbolName: string) {
         .replace(/-command$/, '').replace(/-controller/, '-');
 }
 
-export function parseControllerConfig(config: ControllerConfig): ParsedCliControllerConfig {
+function parseControllerConfig(config: ControllerConfig): ParsedCliControllerConfig {
     let name = config.name || '';
     let description = '';
     if (!name && config.controller) {
@@ -352,7 +350,7 @@ function printHelp(script: string, command: ParsedCliControllerConfig, writer: C
     }
 }
 
-export type CommandWriter = (...message: any[]) => void;
+type CommandWriter = (...message: any[]) => void;
 
 interface ParameterMeta {
     flag: boolean;
@@ -604,7 +602,7 @@ function getActualCliParameterName(parameter: { prefix: string, name: string })
     return parameter.prefix ? parameter.prefix + '.' + parameter.name : parameter.name;
 }
 
-export async function runCommand(
+async function runCommand(
     config: ParsedCliControllerConfig,
     argv: string[],
     injector: InjectorContext,

packages/app/src/configuration.ts

@@ -14,7 +14,7 @@ import { existsSync, readFileSync } from 'fs';
 class ConfigOptionNotFound extends Error {
 }
 
-export function resolveEnvFilePath(path: string): string | undefined {
+function resolveEnvFilePath(path: string): string | undefined {
     const resolvedPath = isAbsolute(path) ? path : findFileUntilPackageRoot(path);
     if (!resolvedPath || !existsSync(resolvedPath)) return undefined;
 
@@ -38,6 +38,9 @@ function findFileUntilPackageRoot(fileName: string): string | undefined {
     }
 }
 
+/**
+ * @internal
+ */
 export class EnvConfiguration {
     protected container: { [name: string]: any } = {};
 

packages/app/src/module.ts

@@ -12,18 +12,12 @@ import { InjectorModule, InjectorModuleConfig, NormalizedProvider, ProviderWithS
 import { AbstractClassType, ClassType, CustomError, ExtractClassType, isClass } from '@deepkit/core';
 import { EventListener, EventToken } from '@deepkit/event';
 import { WorkflowDefinition } from '@deepkit/workflow';
-import {
-    getPartialSerializeFunction,
-    ReflectionFunction,
-    ReflectionKind,
-    ReflectionMethod,
-    resolveReceiveType,
-    serializer,
-    Type,
-    TypeClass,
-} from '@deepkit/type';
+import { getPartialSerializeFunction, ReflectionFunction, ReflectionKind, ReflectionMethod, resolveReceiveType, serializer, Type, TypeClass } from '@deepkit/type';
 import { ControllerConfig } from './service-container.js';
 
+/**
+ * @internal
+ */
 export interface MiddlewareConfig {
     getClassTypes(): ClassType[];
 }
@@ -44,6 +38,9 @@ export interface AddedListener {
     order: number;
 }
 
+/**
+ * Stringifies the listener to a human-readable string.
+ */
 export function stringifyListener(listener: AddedListener): string {
     if (listener.classType) {
         return listener.classType.name + '.' + listener.methodName;
@@ -182,7 +179,6 @@ export interface CreateModuleDefinition extends ModuleDefinition {
 }
 
 export type FunctionalModule = (module: AppModule<any>) => void;
-export type FunctionalModuleFactory = (...args: any[]) => (module: AppModule<any>) => void;
 
 export interface RootModuleDefinition extends ModuleDefinition {
     /**
@@ -198,13 +194,17 @@ let moduleId = 0;
 
 /**
  * @reflection never
+ * @internal
  */
 export type DeepPartial<T> =
     T extends string | number | bigint | boolean | null | undefined | symbol | Date | Set<any> | Map<any, any> | Uint8Array | ArrayBuffer | ArrayBufferView | Error | RegExp | Function | Promise<any> ? T :
         Partial<{
             [P in keyof T]: DeepPartial<T[P]>;
         }>;
 
+/**
+ * @internal
+ */
 export interface AppModuleClass<C extends InjectorModuleConfig> {
     new(config?: DeepPartial<C>): AppModule<C>;
 }

packages/app/tests/application.spec.ts

@@ -1,12 +1,14 @@
 import { beforeEach, expect, test } from '@jest/globals';
-import { App, AppErrorEvent, AppEvent, AppExecutedEvent, onAppError, onAppExecute, onAppExecuted, onAppShutdown } from '../src/app.js';
-import { ClassType, Inject, isClass } from '@deepkit/core';
+import { App, onAppError, onAppExecute, onAppExecuted, onAppShutdown } from '../src/app.js';
+import { ClassType, getCurrentDirName, Inject, isClass } from '@deepkit/core';
 import { ProviderWithScope, Token } from '@deepkit/injector';
 import { AppModule, createModule, createModuleClass } from '../src/module.js';
-import { BaseEvent, DataEvent, DataEventToken, EventDispatcher, eventDispatcher, EventToken } from '@deepkit/event';
+import { BaseEvent, DataEvent, DataEventToken, EventDispatcher, eventDispatcher, EventOfEventToken, EventToken } from '@deepkit/event';
 import { cli, Command, Flag } from '../src/command.js';
 import { ControllerConfig, ServiceContainer } from '../src/service-container.js';
 
+const dirname = getCurrentDirName();
+
 Error.stackTraceLimit = 100;
 
 class BaseConfig {
@@ -53,7 +55,7 @@ test('loadConfigFromEnvVariables', async () => {
 
 test('loadConfigFromEnvFile', async () => {
     const app = new App({ config: Config, providers: [Service], imports: [new BaseModule] });
-    app.loadConfigFromEnv({ envFilePath: __dirname + '/test.env' });
+    app.loadConfigFromEnv({ envFilePath: dirname + '/test.env' });
 
     const service = app.get(Service);
     expect(service.token).toBe('changed5');
@@ -595,10 +597,10 @@ test('events', async () => {
     class MyService {
     }
 
-    let executeEvent: AppEvent | undefined = undefined;
-    let executedEvent: AppExecutedEvent | undefined = undefined;
-    let errorEvent: AppErrorEvent | undefined = undefined;
-    let shutdownEvent: AppEvent | undefined = undefined;
+    let executeEvent: EventOfEventToken<typeof onAppExecute> | undefined = undefined;
+    let executedEvent: EventOfEventToken<typeof onAppExecuted> | undefined = undefined;
+    let errorEvent: EventOfEventToken<typeof onAppError> | undefined = undefined;
+    let shutdownEvent: EventOfEventToken<typeof onAppShutdown> | undefined = undefined;
 
     const app = new App({
             providers: [MyService],