@herrromich/az-functions 1.0.0

package/dist/src/logger/trie-search.service.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A service that provides a trie data structure for searching and storing values associated with string keys.
+ *
+ * This class can be used for providing of log levels for loggers based on their names, where the logger names are structured in a hierarchical manner using a separator (e.g., '.').
+ *
+ * @template T - The type of values stored in the trie.
+ *
+ * @example
+ * export class TrieSearchLogLevelProvider implements LogLevelProvider {
+ *   private readonly trieSearchService: TrieSearchService<LogLevel>;
+ *
+ *   constructor(@inject(DEFAULT_LOG_LEVEL) @optional() defaultLogLevel: LogLevel) {
+ *     this.trieSearchService = new TrieSearchService('.', defaultLogLevel);
+ *     this.trieSearchService.set(SYSTEM_LOGGER_NAME_PREFIX, 'silly');
+ *     this.trieSearchService.set(PERSISTENCE_KYSELY_LOGGER_NAME, 'error');
+ *   }
+ *
+ *   getLogLevel(loggerName: string | undefined): LogLevel | undefined {
+ *     return this.trieSearchService.find(loggerName);
+ *   }
+ * }
+ */
+export declare class TrieSearchService<T> {
+    private readonly trieSeparator;
+    private readonly root;
+    /**
+     * Creates an instance of TrieSearchService.
+     *
+     * @param trieSeparator - The separator used to split the keys into parts for the trie structure.
+     * @param rootValue - The value associated with the root of the trie.
+     */
+    constructor(trieSeparator: string, rootValue: T);
+    /**
+     * Retrieves all key-value pairs in the trie that match the specified prefix.
+     *
+     * @param prefix - An optional prefix to filter the keys. If provided, only keys starting with this prefix will be included in the result.
+     * @returns A record containing all matching key-value pairs.
+     */
+    getAll(prefix?: string): Record<string, T>;
+    private getAllChildren;
+    /**
+     * Finds the value associated with the longest matching prefix of the specified key in the trie.
+     *
+     * @param key - The key to search for in the trie. If undefined, the root value will be returned.
+     * @returns The value associated with the longest matching prefix of the key, or undefined if no match is found.
+     */
+    find(key: string | undefined): T;
+    /**
+     * Retrieves the value associated with the specified key in the trie.
+     *
+     * @param key - The key to search for in the trie.
+     * @returns The value associated with the key, or undefined if the key is not found.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Sets the value associated with the specified key in the trie. If the value is undefined, the key will be removed from the trie.
+     *
+     * @param key - The key to set or remove in the trie.
+     * @param value - The value to associate with the key. If undefined, the key will be removed.
+     */
+    set(key: string, value?: T): void;
+    private traverse;
+    private concatNodes;
+    private removeNodes;
+}

package/dist/src/middleware.d.ts

@@ -0,0 +1,10 @@
+import { Container } from 'inversify';
+import { PlatformConfiguration } from './platform';
+/**
+ * Starts the platform based on the provided configuration and the current platform mode.
+ *
+ * The function initializes the necessary containers and services, and then either prints the OpenAPI specification or starts the platform with the registered trigger handlers.
+ * @param config The platform configuration.
+ * @returns The platform container.
+ */
+export declare function startPlatform(config: PlatformConfiguration): Container;

package/dist/src/platform/azure-platform.d.ts

@@ -0,0 +1,15 @@
+import { SwaggerHandlingService } from '../http-controller';
+import { Container } from 'inversify';
+import { LoggerFactory } from '../logger';
+import { TriggerHandlerClass } from '../shared';
+import { RegisterTriggerHandlerFactory } from './register-trigger-handler.factory';
+export declare class AzurePlatform {
+    private readonly platformContainer;
+    private readonly registerHandler;
+    private readonly swaggerHandlingService;
+    private readonly logger;
+    constructor(loggerFactory: LoggerFactory, platformContainer: Container, registerHandler: RegisterTriggerHandlerFactory, swaggerHandlingService: SwaggerHandlingService);
+    start(triggerHandlerClasses: TriggerHandlerClass[]): void;
+    private registerStartupService;
+    private registerSwaggerUi;
+}

package/dist/src/platform/index.d.ts

@@ -0,0 +1,5 @@
+import { ContainerModule } from 'inversify';
+export * from './azure-platform';
+export * from './model';
+export { IStartupService, STARTUP_SERVICE } from './startup.service';
+export declare const PlatformModule: ContainerModule;

package/dist/src/platform/model.d.ts

@@ -0,0 +1,18 @@
+import { RestApplication } from '../http-controller';
+import { ContainerModule } from 'inversify';
+import { LoggerConfiguration } from '../logger';
+import { TriggerHandlerClass } from '../shared';
+/**
+ * Represents the configuration for the platform, including trigger handlers, REST applications, modules, and optional logger configuration.
+ *
+ * @property triggerHandlerClasses The trigger handler classes to be registered with the platform.
+ * @property restApplications Optional REST applications to be registered with the platform.
+ * @property modules The container modules to be loaded into the platform container.
+ * @property loggerConfiguration Optional logger configuration for the platform.
+ */
+export interface PlatformConfiguration {
+    triggerHandlerClasses: TriggerHandlerClass[];
+    restApplications?: RestApplication[];
+    modules: ContainerModule[];
+    loggerConfiguration?: LoggerConfiguration;
+}

package/dist/src/platform/register-trigger-handler.factory.d.ts

@@ -0,0 +1,5 @@
+import { ResolutionContext } from 'inversify';
+import { TriggerHandlerClass } from '../shared';
+export declare const REGISTER_TRIGGER_HANDLER_FACTORY: import("inversify").ServiceIdentifier<RegisterTriggerHandlerFactory>;
+export type RegisterTriggerHandlerFactory = (triggerHandlerClass: TriggerHandlerClass) => void;
+export declare function bindRegisterTriggerHandlerFactory(context: ResolutionContext): RegisterTriggerHandlerFactory;

package/dist/src/platform/startup.service.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Represents a service responsible for performing startup tasks.
+ *
+ * This interface defines a single method, `startup`, which is expected to be implemented by any class that provides startup functionality.
+ * The `startup` method should return a Promise that resolves when the startup tasks are complete.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class MyStartupService implements IStartupService {
+ *   async startup(): Promise<void> {
+ *     // Perform startup tasks here
+ *   }
+ * }
+ * ...
+ * export const StartupModule = new ContainerModule((bind) => {
+ *   bind<IStartupService>(STARTUP_SERVICE).to(MyStartupService);
+ * });
+ * ...
+ * startPlatform({
+ * ...
+ *   modules: [
+ *   ...
+ *    StartupModule,
+ *   ...
+ *   ],
+ * ```
+ */
+export interface IStartupService {
+    startup(): Promise<void>;
+}
+/**
+ * A unique identifier for the `IStartupService` in the dependency injection container.
+ * This identifier can be used to register and retrieve the startup service implementation.
+ */
+export declare const STARTUP_SERVICE: import("inversify").ServiceIdentifier<IStartupService>;

package/dist/src/platform/system-logger-name.provider.d.ts

@@ -0,0 +1 @@
+export declare function systemLoggerNameProvider(stackEntry?: string): string | undefined;

package/dist/src/platform.container.d.ts

@@ -0,0 +1,3 @@
+import { Container } from 'inversify';
+import { LoggerConfiguration } from './logger';
+export declare function providePlatformContainer(loggerConfiguration: LoggerConfiguration | undefined): Container;

package/dist/src/security/index.d.ts

@@ -0,0 +1,2 @@
+export * from './security-context';
+export * from './security.model';

package/dist/src/security/security-context.d.ts

@@ -0,0 +1,22 @@
+import { PlatformContextManager } from '../context';
+import { AuthContext } from './security.model';
+/**
+ * SecurityContext provides access to the current authentication context.
+ *
+ * It retrieves the authentication information from the platform context manager, which is typically set up during the request handling process.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const securityContext = container.get(SecurityContext);
+ * const authContext = securityContext.getAuthentication();
+ * if (authContext) {
+ *   // Access user information, roles, etc.
+ * }
+ * ```
+ */
+export declare class SecurityContext {
+    private readonly contextManager;
+    constructor(contextManager: PlatformContextManager);
+    getAuthentication(): AuthContext | undefined;
+}

package/dist/src/security/security.model.d.ts

@@ -0,0 +1,37 @@
+import { AzFunctionsErrorOptions, AzFunctionsRuntimeError } from '../shared';
+/**
+ *
+ */
+export declare class AuthenticationError extends AzFunctionsRuntimeError {
+    constructor(message?: string, options?: AzFunctionsErrorOptions);
+}
+/**
+ * Represents an authenticated principal in the authentication context.
+ * @property {string} subject - The unique identifier of the principal (e.g., user ID).
+ * @property {string} type - The type of the principal (e.g., "user", "service").
+ * @property {string} scheme - The authentication scheme used for the principal (e.g., "bearer", "basic").
+ * @property {string[]} scopes - An array of scopes associated with the principal.
+ * @property {Record<string, unknown>} [meta] - Optional additional metadata about the principal.
+ */
+export interface Principal {
+    subject: string;
+    type: string;
+    scheme: string;
+    scopes: string[];
+    meta?: Record<string, unknown>;
+}
+/**
+ * Represents the authentication context for a request.
+ * @property {Principal | null} principal - The primary authenticated principal, or null if not authenticated.
+ * @property {Principal[]} principals - An array of all principals associated with the request.
+ * @property {string[]} scopes - An array of scopes associated with the authenticated principal.
+ */
+export interface AuthContext {
+    principal: Principal | null;
+    principals: Principal[];
+    scopes: string[];
+}
+/**
+ * A unique key for accessing the authentication context in the platform context.
+ */
+export declare const AUTHENTICATION_CONTEXT_KEY: import("../context").PlatformContextValueKey<AuthContext>;

package/dist/src/shared/decorators/decorators.d.ts

@@ -0,0 +1,37 @@
+import { ArgMetadata, ArgMetadataProvider, ArgsMetadata, CommonArgMetadata } from './decorators.model';
+export declare function adjustMetadata<T extends ArgMetadata>(metadataKey: unknown, operationArg: T, argMetadataProvider: ArgMetadataProvider<T>): ParameterDecorator;
+export declare function initializeMetadata<T extends ArgMetadata>(target: object, propertyKey: string | symbol, argMetadataProvider: ArgMetadataProvider<T>): ArgsMetadata<T>;
+export declare function getCommonArg(): CommonArgMetadata;
+/**
+ * Parameter decorator to inject the Azure Functions `InvocationContext` into a function parameter.
+ *
+ * @example
+ * ```ts
+ * @HttpController({
+ *  path: '/users',
+ *  })
+ *  export class UserController {
+ *  constructor(private readonly adUsersService: AdUsersService
+ *   private readonly usersMapper: UsersMapper) {}
+ *
+ *  @Get({
+ *   directResponse: {
+ *    contentSchema: usersResponseDtoSchema,
+ *    description: 'Returns a list of users',
+ *   },
+ *  })
+ *  async getUsers(@InvocationCtx() invocationCtx: InvocationContext): Promise<UsersResponseDto> {
+ *   invocationCtx.log.info('Requesting users.');
+ *
+ *   const adUsers = await this.adUsersService.getUsers();
+ *   const items = this.usersMapper.fromAdUsers(adUsers);
+ *
+ *   invocationCtx.log.info('Responding users.');
+ *   invocationCtx.log.debug('Responding %n users.', items.length);
+ *
+ *   return { items };
+ *  }
+ * }
+ * ```
+ */
+export declare function InvocationCtx(): ParameterDecorator;

package/dist/src/shared/decorators/decorators.model.d.ts

@@ -0,0 +1,13 @@
+import { AzFunctionsSystemError } from '../platform.model';
+export interface ArgMetadata {
+    type: string;
+}
+export interface CommonArgMetadata extends ArgMetadata {
+    type: 'invocationContext' | 'undefined';
+}
+export interface ArgsMetadata<T extends ArgMetadata> {
+    args: T[];
+}
+export type ArgMetadataProvider<T extends ArgMetadata> = (paramType: unknown) => T;
+export declare class AzFunctionsDecoratorError extends AzFunctionsSystemError {
+}

package/dist/src/shared/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export * from './decorators';
+export * from './decorators.model';

package/dist/src/shared/index.d.ts

@@ -0,0 +1,8 @@
+import { ContainerModule } from 'inversify';
+export { TrieSearchService } from '../logger/trie-search.service';
+export * from './decorators';
+export { serviceIdentifier } from './ioc-container.utils';
+export * from './platform.model';
+export * from './trigger-handler-metadata.reader';
+export { parseWithZod, ZodParserError } from './zod-parser-wrapper';
+export declare const SharedModule: ContainerModule;

package/dist/src/shared/ioc-container.utils.d.ts

@@ -0,0 +1,7 @@
+import { ServiceIdentifier } from 'inversify';
+/**
+ * Creates a typed service identifier for use with InversifyJS.
+ * @param key The unique key for the service.
+ * @returns A symbol that can be used as a service identifier.
+ */
+export declare function serviceIdentifier<T>(key: string): ServiceIdentifier<T>;

package/dist/src/shared/platform.model.d.ts

@@ -0,0 +1,44 @@
+import { Container } from 'inversify';
+import { z } from 'zod';
+export declare const BASE_DIR: import("inversify").ServiceIdentifier<string>;
+export declare const PLATFORM_CONTAINER: import("inversify").ServiceIdentifier<Container>;
+export declare const FUNCTION_HANDLER_METADATA: unique symbol;
+export declare const platformModeSchema: z.ZodCatch<z.ZodEnum<{
+    start: "start";
+    "print-open-api": "print-open-api";
+}>>;
+/**
+ * Options for creating an AzFunctionsError.
+ * @property {Record<string, unknown>} [details] - Optional additional details about the error.
+ */
+export interface AzFunctionsErrorOptions extends ErrorOptions {
+    details?: Record<string, unknown>;
+}
+export declare abstract class AzFunctionsError extends Error {
+    protected _details?: Record<string, unknown>;
+    get details(): Readonly<Record<string, unknown>> | undefined;
+    protected constructor(message?: string, options?: AzFunctionsErrorOptions);
+}
+export declare abstract class AzFunctionsSystemError extends AzFunctionsError {
+    constructor(message?: string, options?: AzFunctionsErrorOptions);
+}
+/**
+ * Abstract base class for runtime errors in Azure Functions.
+ * @example
+ * ```ts
+ * class MyRuntimeError extends AzFunctionsRuntimeError {}
+ * ```
+ */
+export declare class AzFunctionsRuntimeError extends AzFunctionsError {
+    constructor(message?: string, options?: AzFunctionsErrorOptions);
+}
+export type TriggerHandlerClass<TInstance extends object = object, TArgs extends unknown[] = any[]> = new (...args: TArgs) => TInstance;
+export interface TriggerHandlerClassMetadata {
+    type: string;
+}
+export declare const TRIGGER_HANDLER_REGISTRATION_SERVICE: import("inversify").ServiceIdentifier<TriggerHandlerRegistrationService>;
+export interface TriggerHandlerRegistrationService {
+    register(triggerHandlerClass: TriggerHandlerClass): void;
+}
+export declare class HandlerArgsParseError extends AzFunctionsRuntimeError {
+}

package/dist/src/shared/trigger-handler-metadata.reader.d.ts

@@ -0,0 +1,6 @@
+import { AzFunctionsSystemError, TriggerHandlerClass, TriggerHandlerClassMetadata } from './platform.model';
+export declare class TriggerHandlerMetadataError extends AzFunctionsSystemError {
+}
+export declare class TriggerHandlerMetadataReader {
+    getHandlerClassMetadata(triggerHandlerClass: TriggerHandlerClass): TriggerHandlerClassMetadata;
+}

package/dist/src/shared/zod-parser-wrapper.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export declare class ZodParserError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare function parseWithZod<T>(schema: z.ZodType<T>, data: unknown): T;