@conduitplatform/module-tools 0.16.26 → 0.17.0-alpha.2

package/dist/index.d.ts

@@ -1,7 +1,490 @@
-export * from './ManagedModule.js';
-export * from './interfaces/index.js';
-export * from './classes/index.js';
-export * from './helpers/index.js';
-export * from './routing/index.js';
-export * from './utilities/index.js';
-export * from './classes/ModuleError.js';
+import { ConduitSchema, DatabaseProvider, ConduitModel, ConduitSchemaOptions, Query, FindOneOptions, FindManyOptions, AuthzOptions, PopulateAuthzOptions, CountDocumentsOptions, ConduitGrpcSdk, HealthCheckStatus, GrpcRequest, HealthCheckRequest, GrpcCallback, HealthCheckResponse, SetConfigRequest, GrpcResponse, SetConfigResponse, GetExportableResourcesRequest, GetExportableResourcesResponse, ExportResourcesRequest, ExportResourcesResponse, ImportResourcesRequest, ImportResourcesResponse, PeerWatchEdge, TYPE, ConduitStringValidation, ConduitNumberValidation, Params, Context, Cookies, ParsedRouterRequest, UnparsedRouterResponse, ConduitSocketParamTypes, ConduitRouteReturnDefinition, ParsedSocketRequest, UnparsedSocketResponse, Indexable, Router, Admin, ConduitMiddlewareOptions, ConduitRouteOptions, ConduitSocketOptions, ConduitRouteActions, ConduitQueryParams, ConduitUrlParams, ConduitReturn, ConduitRoute, GrpcError, ModuleErrorDefinition } from '@conduitplatform/grpc-sdk';
+import { EventEmitter } from 'events';
+import { ServerWritableStream, Server } from '@grpc/grpc-js';
+import convict from 'convict';
+
+declare class ConduitActiveSchema<T> extends ConduitSchema {
+    private readonly dbInstance;
+    constructor(dbInstance: DatabaseProvider, name: string, fields?: ConduitModel, modelOptions?: ConduitSchemaOptions, collectionName?: string);
+    findOne(query: Query<T>, options?: FindOneOptions): Promise<T | null>;
+    findMany(query: Query<T>, options?: FindManyOptions): Promise<T[]>;
+    create(query: Query<T>, options?: AuthzOptions): Promise<T>;
+    createMany(query: Query<T>[], options?: AuthzOptions): Promise<T[]>;
+    findByIdAndUpdate(id: string, document: Query<T>, options?: PopulateAuthzOptions): Promise<T | null>;
+    findByIdAndReplace(id: string, document: Query<T>, options?: PopulateAuthzOptions): Promise<T | null>;
+    replaceOne(filterQuery: Query<T>, query: Query<T>, options?: PopulateAuthzOptions): Promise<any>;
+    updateOne(filterQuery: Query<T>, query: Query<T>, options?: PopulateAuthzOptions): Promise<any>;
+    updateMany(filterQuery: Query<T>, query: Query<T>, options?: PopulateAuthzOptions): Promise<any>;
+    deleteOne(query: Query<T>, options?: AuthzOptions): Promise<any>;
+    deleteMany(query: Query<T>, options?: AuthzOptions): Promise<any>;
+    countDocuments(query: Query<T>, options?: CountDocumentsOptions): Promise<number>;
+}
+
+declare class GrpcServer {
+    private grpcServer?;
+    private started;
+    private startedOnce;
+    private _serviceNames;
+    private scheduledRestart;
+    private _postponeRequests;
+    private _useForce?;
+    private _services;
+    constructor(port?: string);
+    waitForReady(): Promise<void>;
+    private _url;
+    get url(): string;
+    createNewServer(useForce?: boolean): Promise<number>;
+    addService(protoPath: string, protoDescription: string, functions: {
+        [name: string]: Function;
+    }, noAuth?: boolean): Promise<GrpcServer>;
+    wait(time: number): Promise<void>;
+    refresh(): Promise<void>;
+    scheduleRefresh(): void;
+    start(): void;
+    private postponeRestart;
+}
+
+/**
+ * Framework-level types for module export/import (GitOps / config-as-code).
+ * Modules that implement getExportableResources(), exportResources(), and importResources()
+ * can participate in unified state export/import via Core.
+ */
+interface ExportableResource {
+    /** e.g. "schemas", "emailTemplates", "resourceDefinitions" */
+    type: string;
+    /** Human-readable description */
+    description: string;
+    /** Import ordering: lower = imported first (e.g. schemas before endpoints) */
+    priority: number;
+}
+/** Per-resource-type arrays of exportable data (e.g. { schemas: [...], customEndpoints: [...] }) */
+interface ExportResult {
+    [resourceType: string]: unknown[];
+}
+/** Per-resource-type import outcome */
+interface ImportResultEntry {
+    created: number;
+    updated: number;
+    failed: number;
+    errors: string[];
+}
+interface ImportResult {
+    [resourceType: string]: ImportResultEntry;
+}
+
+declare abstract class ConduitServiceModule {
+    protected readonly _moduleName: string;
+    protected _serviceName?: string;
+    protected _address: string;
+    protected grpcServer: GrpcServer;
+    protected readonly events: EventEmitter;
+    private _serviceHealthState;
+    protected constructor(moduleName: string);
+    private _registered;
+    set registered(registered: boolean);
+    protected _port: string;
+    get port(): string;
+    private _grpcSdk;
+    get grpcSdk(): ConduitGrpcSdk;
+    set grpcSdk(grpcSdk: ConduitGrpcSdk);
+    get healthState(): HealthCheckStatus;
+    updateHealth(state: HealthCheckStatus, init?: boolean): void;
+    healthCheck(call: GrpcRequest<HealthCheckRequest>, callback: GrpcCallback<HealthCheckResponse>): void;
+    healthWatch(call: ServerWritableStream<HealthCheckRequest, HealthCheckResponse>): void;
+    abstract setConfig(call: GrpcRequest<SetConfigRequest>, callback: GrpcResponse<SetConfigResponse>): Promise<void>;
+    /** Override to declare which resource types this module can export/import. Default: none. */
+    protected getExportableResources(): ExportableResource[];
+    /** Override to export resources. resourceTypes empty = export all. Default: empty. */
+    protected exportResources(_resourceTypes: string[]): Promise<ExportResult>;
+    /** Override to import resources. Default: no-op. */
+    protected importResources(_resources: ExportResult): Promise<ImportResult>;
+    protected getExportableResourcesHandler(_call: GrpcRequest<GetExportableResourcesRequest>, callback: GrpcResponse<GetExportableResourcesResponse>): void;
+    protected exportResourcesHandler(call: GrpcRequest<ExportResourcesRequest>, callback: GrpcResponse<ExportResourcesResponse>): Promise<void>;
+    protected importResourcesHandler(call: GrpcRequest<ImportResourcesRequest>, callback: GrpcResponse<ImportResourcesResponse>): Promise<void>;
+    protected addHealthCheckService(): Promise<void>;
+    protected addModuleService(): Promise<void>;
+}
+
+declare class ConfigController {
+    private static instance;
+    private _config;
+    get config(): any;
+    set config(config: any);
+    static getInstance(): ConfigController;
+}
+
+interface ConduitService {
+    readonly protoPath: string;
+    readonly protoDescription: string;
+    functions: {
+        [p: string]: (call: GrpcRequest<any>, callback: GrpcResponse<any>) => void | Promise<void>;
+    };
+}
+
+declare enum ModuleLifecycleStage {
+    CREATE_GRPC = "creat-grpc-server",
+    PRE_SERVER_START = "pre-grpc-start",
+    SERVER_STARTED = "grpc-server-started",
+    PRE_REGISTER = "pre-register",
+    POST_REGISTER = "post-register"
+}
+
+interface ConduitPeerWatchEntry {
+    module: string;
+    edge?: PeerWatchEdge;
+}
+/** Optional `conduit.peers` block in a module `package.json`. */
+interface ConduitPeersManifest {
+    peers?: {
+        await?: string[];
+        watch?: ConduitPeerWatchEntry[];
+    };
+}
+interface ConduitPackageJson {
+    name?: string;
+    conduit?: ConduitPeersManifest;
+}
+declare function readConduitPeersManifest(moduleRootDir?: string): ConduitPeersManifest | null;
+
+declare abstract class ManagedModule<T> extends ConduitServiceModule {
+    readonly config?: convict.Config<T>;
+    configOverride: boolean;
+    service?: ConduitService;
+    protected abstract readonly configSchema?: object;
+    protected abstract readonly metricsSchema?: object;
+    private readonly serviceAddress;
+    private readonly servicePort;
+    private _moduleState;
+    private _declaredPeerWatchDisposers;
+    private _cachedPeersManifest;
+    private _lastPeerBatchStates;
+    private readonly _peerManifestRoot?;
+    private _configInitialized;
+    private _pendingConfigUpdates;
+    private _processingConfig;
+    protected constructor(moduleName: string, peerManifestRoot?: string);
+    get name(): string;
+    get address(): string;
+    start(): Promise<void>;
+    /**
+     * This is the first function triggered on module spin up.
+     * @param address {string} external address:port of service (LoadBalancer)
+     * @param port {string} port to bring up gRPC service
+     */
+    initialize(address: string, port: string): void;
+    /**
+     * This is triggered before spinning up the Grpc Server
+     * of the module. On this stage, the redis bus and state have
+     * not yet been initialized, and only communications with Conduit core
+     * have been established.
+     */
+    preServerStart(): Promise<void>;
+    /**
+     * This is triggered right after Grpc Server start.
+     * At this stage the core module will communicate with your service
+     * for health checks, and the Bus and State management mechanics
+     * are online and available.
+     */
+    onServerStart(): Promise<void>;
+    /**
+     * Triggers right before registering the module with Conduit Core.
+     */
+    preRegister(): Promise<void>;
+    /**
+     * Triggers when module has been registered with Conduit Core
+     * This is the step where you should initialize your
+     * module's general routing (admin or client) and any other operation,
+     * that would require other modules being able to reach you
+     */
+    onRegister(): Promise<void>;
+    /**
+     * This is triggered when the module receives new configuration.
+     * At this step the configuration has not been checked yet,
+     * and has only been parsed.
+     * @param config
+     */
+    preConfig(config: T): Promise<T>;
+    /**
+     * This is triggered when new configuration has been applied.
+     * This happens either when changes are being made on the configuration,
+     * or on module start up, where the config is recovered from the database.
+     * In either case the configuration is now available through the
+     * Config Controller of the sdk.
+     */
+    onConfig(): Promise<void>;
+    /**
+     * Registers common and module-specific metric types.
+     */
+    registerMetrics(): Promise<void>;
+    /**
+     * Initializes metric startup values.
+     * Implemented by individual modules.
+     */
+    initializeMetrics(): Promise<void>;
+    protected getPeerManifestRoot(): string;
+    protected loadConduitPeersManifest(): ConduitPeersManifest | null;
+    private validateDeclaredPeerNames;
+    protected awaitPeersFromManifest(): Promise<void>;
+    protected registerDeclaredPeerWatches(): void;
+    protected disposeDeclaredPeerWatches(): void;
+    protected onDeclaredPeerConnectionUpdate(_moduleName: string, _serving: boolean): void;
+    createGrpcServer(): Promise<void>;
+    startGrpcServer(): Promise<void>;
+    setConfig(call: GrpcRequest<SetConfigRequest>, callback: GrpcResponse<SetConfigResponse>): Promise<void>;
+    /** Used to update the module's configuration on initial Redis/DB reconciliation. */
+    handleConfigSyncUpdate(): Promise<void>;
+    /** Serializes config updates; waits for initial lifecycle before draining. */
+    private _drainConfigQueue;
+    private preRegisterLifecycle;
+    private postRegisterLifecycle;
+}
+
+declare class ConduitStringConstructor {
+    private constructor();
+    static get Optional(): TYPE.String;
+    static get Required(): {
+        type: TYPE.String;
+        required: true;
+    };
+    static RequiredWith(rules: ConduitStringValidation): {
+        type: TYPE.String;
+        required: true;
+        validate: ConduitStringValidation;
+    };
+    static OptionalWith(rules: ConduitStringValidation): {
+        type: TYPE.String;
+        required: false;
+        validate: ConduitStringValidation;
+    };
+}
+declare const ConduitString: typeof ConduitStringConstructor;
+declare class ConduitNumberConstructor {
+    private constructor();
+    static get Optional(): TYPE.Number;
+    static get Required(): {
+        type: TYPE.Number;
+        required: true;
+    };
+    static RequiredWith(rules: ConduitNumberValidation): {
+        type: TYPE.Number;
+        required: true;
+        validate: ConduitNumberValidation;
+    };
+    static OptionalWith(rules: ConduitNumberValidation): {
+        type: TYPE.Number;
+        required: false;
+        validate: ConduitNumberValidation;
+    };
+}
+declare const ConduitNumber: typeof ConduitNumberConstructor;
+declare class ConduitBooleanConstructor {
+    private constructor();
+    static get Optional(): TYPE.Boolean;
+    static get Required(): {
+        type: TYPE.Boolean;
+        required: true;
+    };
+}
+declare const ConduitBoolean: typeof ConduitBooleanConstructor;
+declare class ConduitDateConstructor {
+    private constructor();
+    static get Optional(): TYPE.Date;
+    static get Required(): {
+        type: TYPE.Date;
+        required: true;
+    };
+}
+declare const ConduitDate: typeof ConduitDateConstructor;
+declare class ConduitObjectIdConstructor {
+    private constructor();
+    static get Optional(): TYPE.ObjectId;
+    static get Required(): {
+        type: TYPE.ObjectId;
+        required: true;
+    };
+}
+declare const ConduitObjectId: typeof ConduitObjectIdConstructor;
+declare class ConduitJSONConstructor {
+    private constructor();
+    static get Optional(): TYPE.JSON;
+    static get Required(): {
+        type: TYPE.JSON;
+        required: true;
+    };
+}
+declare const ConduitJson: typeof ConduitJSONConstructor;
+declare class ConduitRelationConstructor {
+    private constructor();
+    static Optional(model: string): {
+        type: TYPE.Relation;
+        model: string;
+        required: false;
+    };
+    static Required(model: string): {
+        type: TYPE.Relation;
+        model: string;
+        required: true;
+    };
+}
+declare const ConduitRelation: typeof ConduitRelationConstructor;
+
+declare function createServer(port: string): Promise<{
+    server: Server;
+    port: number;
+}>;
+declare function addServiceToServer(server: Server, protoPath: string, descriptorObject: string, functions: {
+    [name: string]: Function;
+}): void;
+
+declare function wrapGrpcFunctions(functions: {
+    [name: string]: Function;
+}, postponeRestart: () => void, noAuth?: boolean): {
+    [name: string]: Function;
+};
+
+declare function createParsedRouterRequest(params: Params, urlParams?: Params, queryParams?: Params, bodyParams?: Params, path?: string, headers?: Headers, context?: Context, cookies?: Cookies): ParsedRouterRequest;
+
+type RouterRequestHandler = (call: ParsedRouterRequest) => Promise<UnparsedRouterResponse>;
+type RouterRequestHandlerCallback = (call: ParsedRouterRequest, callback: (response: UnparsedRouterResponse) => void) => Promise<UnparsedRouterResponse | undefined | void>;
+type SocketRequestHandler = (call: ParsedSocketRequest) => Promise<UnparsedSocketResponse>;
+type SocketRequestHandlerCallback = (call: ParsedSocketRequest, callback: (response: UnparsedSocketResponse) => void) => Promise<UnparsedSocketResponse | undefined | void>;
+type RequestHandlers = RouterRequestHandler | RouterRequestHandlerCallback;
+type SocketRequestHandlers = SocketRequestHandler | SocketRequestHandlerCallback;
+interface SocketEventHandler {
+    params?: ConduitSocketParamTypes;
+    returnType?: ConduitRouteReturnDefinition;
+    handler: SocketRequestHandlers;
+}
+declare function wrapRouterGrpcFunction(fun: RequestHandlers | SocketRequestHandlers, routerType: string): (call: Indexable, callback: any) => void;
+
+declare class RoutingController {
+    private _routeHandlers;
+    handleRequest(call: GrpcRequest<any>, callback: GrpcCallback<any>): void;
+    setRoutes(routes: {
+        [key: string]: (call: any, callback: any) => void;
+    }): void;
+}
+
+declare class RoutingManager {
+    private readonly _router;
+    private readonly _server;
+    private _moduleRoutes;
+    static ClientController: RoutingController;
+    static AdminController: RoutingController;
+    private _routeHandlers;
+    private readonly isAdmin;
+    constructor(_router: Router | Admin, _server: GrpcServer);
+    get(path: string): RouteBuilder;
+    post(path: string): RouteBuilder;
+    delete(path: string): RouteBuilder;
+    update(path: string): RouteBuilder;
+    patch(path: string): RouteBuilder;
+    clear(): void;
+    middleware(input: ConduitMiddlewareOptions, handler: RequestHandlers): void;
+    route(input: ConduitRouteOptions, type: ConduitRouteReturnDefinition, handler: RequestHandlers): void;
+    socket(input: ConduitSocketOptions, events: Record<string, SocketEventHandler>): void;
+    registerRoutes(): Promise<any>;
+    private generateGrpcName;
+    private extractNameFromPath;
+    private parseRouteObject;
+}
+
+declare class RouteBuilder {
+    private readonly manager?;
+    private readonly _options;
+    private _returns;
+    private _handler;
+    constructor(manager?: RoutingManager | undefined);
+    method(action: ConduitRouteActions): RouteBuilder;
+    name(name: string): RouteBuilder;
+    description(description: string): RouteBuilder;
+    cacheControl(cache: string): RouteBuilder;
+    middleware(middleware: string | string[], allowDuplicates?: boolean): RouteBuilder;
+    path(path: string): RouteBuilder;
+    queryParams(params: ConduitQueryParams): RouteBuilder;
+    urlParams(params: ConduitUrlParams): RouteBuilder;
+    bodyParams(params: ConduitModel): RouteBuilder;
+    strictParams(strict: boolean): RouteBuilder;
+    rateLimit(maxRequests: number, resetInterval: number): RouteBuilder;
+    return(name: string, fields: ConduitReturn): RouteBuilder;
+    handler(fn: RequestHandlers): RouteBuilder;
+    add(): void;
+    build(): ConduitRoute;
+}
+
+declare function wrapFunctionsAsync(functions: {
+    [name: string]: RequestHandlers | SocketRequestHandlers;
+}, routerType: 'admin' | 'client'): {
+    [name: string]: (call: Indexable, callback?: Indexable) => void;
+};
+
+declare const initializeSdk: (coreUrl: string, moduleName: string, watchModules?: boolean, serviceHealthStatusGetter?: () => HealthCheckStatus) => ConduitGrpcSdk;
+
+declare function linearBackoffTimeout(onTry: (stop: () => void) => void, delay: number, reps?: number, onFailure?: () => void): {
+    clear: () => void;
+};
+/**
+ * Registers a timeout with linear backoff.
+ * onFailure() only runs on rep exhaustion.
+ * @param {() => Promise<boolean>} onTry - Async handler, returns 'continue' boolean flag
+ */
+declare function linearBackoffTimeoutAsync(onTry: () => Promise<boolean>, delay: number, reps?: number, onFailure?: () => void | Promise<void>, startNow?: boolean): Promise<void>;
+
+declare function merge<T extends object>(objA: T, objB: T): T;
+
+/**
+ * Reusable helpers for module export/import (GitOps).
+ * Standardizes stripping internal fields and optional export/import flows.
+ */
+
+/** Fields removed from documents when exporting (so they are not versioned). */
+declare const DEFAULT_STRIP_FIELDS: readonly ["_id", "createdAt", "updatedAt", "__v"];
+/**
+ * Removes internal and optionally extra fields from a single document.
+ * Does not mutate the original if the result would differ.
+ */
+declare function stripInternalFields(obj: Record<string, unknown>, additionalFields?: string[]): Record<string, unknown>;
+interface SanitizeForExportOptions {
+    /** Extra field names to remove (in addition to DEFAULT_STRIP_FIELDS). */
+    excludeFields?: string[];
+}
+/**
+ * Returns a copy of each document with internal fields stripped.
+ * Use after fetching from DB to produce export-safe arrays.
+ */
+declare function sanitizeDocumentsForExport<T extends Record<string, unknown>>(documents: T[], options?: SanitizeForExportOptions): Record<string, unknown>[];
+/**
+ * Minimal model interface for export: can return all records.
+ */
+interface ExportModelAdapter {
+    findMany(query?: Record<string, unknown>, options?: {
+        select?: string;
+    }): Promise<Record<string, unknown>[]>;
+}
+/**
+ * Fetches all documents from the adapter and returns them with internal fields stripped.
+ */
+declare function exportModel(adapter: ExportModelAdapter, options?: SanitizeForExportOptions & {
+    query?: Record<string, unknown>;
+    select?: string;
+}): Promise<Record<string, unknown>[]>;
+/**
+ * Minimal model interface for import: find by key, create, update.
+ */
+interface ImportModelAdapter {
+    keyField: string;
+    findOne(query: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    create(doc: Record<string, unknown>): Promise<Record<string, unknown>>;
+    updateOne(filter: Record<string, unknown>, doc: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Upserts records by keyField. Returns counts and errors for ImportResultEntry.
+ */
+declare function importModel(adapter: ImportModelAdapter, records: Record<string, unknown>[], options?: SanitizeForExportOptions): Promise<ImportResultEntry>;
+
+declare class ModuleError extends GrpcError {
+    debugLogInfo?: string;
+    constructor(errorDefinition: ModuleErrorDefinition, debugLogInfo?: string);
+}
+
+export { ConduitActiveSchema, ConduitBoolean, ConduitDate, ConduitJson, ConduitNumber, ConduitObjectId, type ConduitPackageJson, type ConduitPeerWatchEntry, type ConduitPeersManifest, ConduitRelation, type ConduitService, ConduitServiceModule, ConduitString, ConfigController, DEFAULT_STRIP_FIELDS, type ExportModelAdapter, type ExportResult, type ExportableResource, GrpcServer, type ImportModelAdapter, type ImportResult, type ImportResultEntry, ManagedModule, ModuleError, ModuleLifecycleStage, type RequestHandlers, RouteBuilder, type RouterRequestHandler, type RouterRequestHandlerCallback, RoutingManager, type SanitizeForExportOptions, type SocketEventHandler, type SocketRequestHandler, type SocketRequestHandlerCallback, type SocketRequestHandlers, addServiceToServer, createParsedRouterRequest, createServer, exportModel, importModel, initializeSdk, linearBackoffTimeout, linearBackoffTimeoutAsync, merge, readConduitPeersManifest, sanitizeDocumentsForExport, stripInternalFields, wrapFunctionsAsync, wrapGrpcFunctions, wrapRouterGrpcFunction };