@treatwell/moleculer-essentials 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Treatwell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# moleculer-essentials

package/dist/context-factory-BWO3xPWE.d.cts

@@ -0,0 +1,520 @@
+import Moleculer__default, { RestSchema, ActionVisibility, Service, ActionCacheOptions, Context, TracingActionOptions, BulkheadOptions, BrokerCircuitBreakerOptions, RetryPolicyOptions, FallbackHandler, ActionHooks, Validators, ActionHandler, ActionSchema, ServiceEvent, ServiceDependency, ServiceHooks, GenericObject, ServiceBroker, Endpoint } from 'moleculer';
+import { ObjectId } from 'bson';
+import { ZodType, z } from 'zod/v4';
+import { Options, ErrorObject } from 'ajv/dist/2019.js';
+
+type UnionToIntersection$1<U> = (U extends any ? (_: U) => void : never) extends (_: infer I) => void ? I : never;
+type SomeJSONSchema = JSONSchemaType<Known, true>;
+type PartialSchema<T> = Partial<JSONSchemaType<T, true>>;
+type JSONType<T extends string, IsPartial extends boolean> = IsPartial extends true ? T | undefined : T;
+interface NumberKeywords {
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    format?: string;
+}
+interface StringKeywords {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+}
+type JSONSchemaType<T, IsPartial extends boolean = false> = (// these two unions allow arbitrary unions of types
+{
+    anyOf: readonly JSONSchemaType<T, IsPartial>[];
+} | {
+    oneOf: readonly JSONSchemaType<T, IsPartial>[];
+} | {
+    allOf: readonly JSONSchemaType<T, true>[];
+} | ({
+    type: readonly (T extends number ? JSONType<'number' | 'integer', IsPartial> : T extends string ? JSONType<'string', IsPartial> : T extends boolean ? JSONType<'boolean', IsPartial> : never)[];
+} & UnionToIntersection$1<T extends number ? NumberKeywords : T extends string ? StringKeywords : T extends boolean ? {} : never>) | ((T extends number ? {
+    type: JSONType<'number' | 'integer', IsPartial>;
+} & NumberKeywords : T extends string ? {
+    type: JSONType<'string', IsPartial>;
+} & StringKeywords : T extends boolean ? {
+    type: JSONType<'boolean', IsPartial>;
+} : T extends Date ? {
+    type: JSONType<'string', IsPartial>;
+    format: 'date-time' | 'date';
+} : T extends Buffer ? {
+    instanceof: 'Buffer';
+} : T extends null ? {
+    type: JSONType<'null', IsPartial>;
+} | {
+    nullable?: true;
+} : T extends ObjectId ? {
+    type: JSONType<'string', IsPartial>;
+    format: 'object-id';
+} : T extends [any, ...any[]] ? {
+    type: JSONType<'array', IsPartial>;
+    items: {
+        readonly [K in keyof T]-?: JSONSchemaType<T[K]> & Nullable<T[K]>;
+    } & {
+        length: T['length'];
+    };
+    minItems: T['length'];
+} & ({
+    maxItems: T['length'];
+} | {
+    additionalItems: false;
+}) : T extends readonly any[] ? {
+    type: JSONType<'array', IsPartial>;
+    items: JSONSchemaType<T[0]>;
+    contains?: PartialSchema<T[0]>;
+    minItems?: number;
+    maxItems?: number;
+    minContains?: number;
+    maxContains?: number;
+    uniqueItems?: true;
+    additionalItems?: never;
+} : T extends Record<string, any> ? {
+    type: JSONType<'object', IsPartial>;
+    required: IsPartial extends true ? Readonly<(keyof T)[]> : Readonly<RequiredMembers<T>[]>;
+    additionalProperties?: boolean | JSONSchemaType<T[string]>;
+    unevaluatedProperties?: boolean | JSONSchemaType<T[string]>;
+    discriminator?: {
+        propertyName: keyof T;
+    };
+    properties?: IsPartial extends true ? Partial<PropertiesSchema<T>> : PropertiesSchema<T>;
+    patternProperties?: Record<string, JSONSchemaType<T[string]>>;
+    propertyNames?: Omit<JSONSchemaType<string>, 'type'> & {
+        type?: 'string';
+    };
+    dependencies?: {
+        [K in keyof T]?: Readonly<(keyof T)[]> | PartialSchema<T>;
+    };
+    dependentRequired?: {
+        [K in keyof T]?: Readonly<(keyof T)[]>;
+    };
+    dependentSchemas?: {
+        [K in keyof T]?: PartialSchema<T>;
+    };
+    minProperties?: number;
+    maxProperties?: number;
+} : T extends null ? {
+    type: JSONType<'null', IsPartial>;
+    nullable: true;
+} : never) & {
+    allOf?: Readonly<PartialSchema<T>[]>;
+    anyOf?: Readonly<PartialSchema<T>[]>;
+    oneOf?: Readonly<PartialSchema<T>[]>;
+    if?: PartialSchema<T>;
+    then?: PartialSchema<T>;
+    else?: PartialSchema<T>;
+    not?: PartialSchema<T>;
+})) & {
+    [keyword: string]: any;
+    $id?: string;
+    $ref?: string;
+    $defs?: Record<string, JSONSchemaType<Known, true>>;
+    definitions?: Record<string, JSONSchemaType<Known, true>>;
+};
+type Known = {
+    [key: string]: Known;
+} | [Known, ...Known[]] | Known[] | number | string | boolean | null;
+type PropertiesSchema<T> = {
+    [K in keyof T]-?: (JSONSchemaType<T[K]> & Nullable<T[K]>) | {
+        $ref: string;
+    };
+};
+type RequiredMembers<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? never : K;
+}[keyof T];
+type Nullable<T> = undefined extends T ? {
+    nullable?: true;
+    const?: never;
+    enum?: Readonly<(T | null)[]>;
+    default?: T | null;
+} : {
+    const?: T;
+    enum?: Readonly<T[]>;
+    default?: T;
+};
+
+interface ContactObject {
+    name?: string;
+    url?: string;
+    email?: string;
+}
+interface LicenseObject {
+    name: string;
+    url?: string;
+}
+interface InfoObject {
+    title: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: ContactObject;
+    license?: LicenseObject;
+    version: string;
+}
+interface ServerVariableObject {
+    enum?: string[];
+    default: string;
+    description?: string;
+}
+interface ServerObject {
+    url: string;
+    description?: string;
+    variables?: Record<string, ServerVariableObject>;
+}
+type PathsObject = Record<string, PathItemObject>;
+interface ExternalDocumentationObject {
+    description?: string;
+    url: string;
+}
+interface ParameterObject extends ParameterBaseObject {
+    name: string;
+    in: string;
+}
+type HeaderObject = ParameterBaseObject;
+interface ParameterBaseObject {
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+    schema?: ReferenceObject | SchemaObject;
+    example?: any;
+    examples?: Record<string, ReferenceObject | ExampleObject>;
+    content?: Record<string, MediaTypeObject>;
+}
+type SchemaObject<T = any, _partial extends boolean = false> = JSONSchemaType<T, _partial>;
+interface ReferenceObject {
+    $ref: string;
+}
+interface ExampleObject {
+    summary?: string;
+    description?: string;
+    value?: any;
+    externalValue?: string;
+}
+interface EncodingObject {
+    contentType?: string;
+    headers?: Record<string, ReferenceObject | HeaderObject>;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+interface MediaTypeObject {
+    schema?: ReferenceObject | SchemaObject;
+    example?: any;
+    examples?: Record<string, ReferenceObject | ExampleObject>;
+    encoding?: Record<string, EncodingObject>;
+}
+interface RequestBodyObject {
+    description?: string;
+    content: Record<string, MediaTypeObject>;
+    required?: boolean;
+}
+interface LinkObject {
+    operationRef?: string;
+    operationId?: string;
+    parameters?: Record<string, any>;
+    requestBody?: any;
+    description?: string;
+    server?: ServerObject;
+}
+interface ResponseObject {
+    description: string;
+    headers?: Record<string, ReferenceObject | HeaderObject>;
+    content?: Record<string, MediaTypeObject>;
+    links?: Record<string, ReferenceObject | LinkObject>;
+}
+type ResponsesObject = Record<string, ReferenceObject | ResponseObject>;
+type SecurityRequirementObject = Record<string, string[]>;
+interface HttpSecurityScheme {
+    type: 'http';
+    description?: string;
+    scheme: string;
+    bearerFormat?: string;
+}
+interface ApiKeySecurityScheme {
+    type: 'apiKey';
+    description?: string;
+    name: string;
+    in: string;
+}
+interface OAuth2SecurityScheme {
+    type: 'oauth2';
+    flows: {
+        implicit?: {
+            authorizationUrl: string;
+            refreshUrl?: string;
+            scopes: Record<string, string>;
+        };
+        password?: {
+            tokenUrl: string;
+            refreshUrl?: string;
+            scopes: Record<string, string>;
+        };
+        clientCredentials?: {
+            tokenUrl: string;
+            refreshUrl?: string;
+            scopes: Record<string, string>;
+        };
+        authorizationCode?: {
+            authorizationUrl: string;
+            tokenUrl: string;
+            refreshUrl?: string;
+            scopes: Record<string, string>;
+        };
+    };
+}
+interface OpenIdSecurityScheme {
+    type: 'openIdConnect';
+    description?: string;
+    openIdConnectUrl: string;
+}
+type SecuritySchemeObject = HttpSecurityScheme | ApiKeySecurityScheme | OAuth2SecurityScheme | OpenIdSecurityScheme;
+type CallbackObject = Record<string, PathItemObject>;
+interface ComponentsObject {
+    schemas?: Record<string, ReferenceObject | SchemaObject>;
+    responses?: Record<string, ReferenceObject | ResponseObject>;
+    parameters?: Record<string, ReferenceObject | ParameterObject>;
+    examples?: Record<string, ReferenceObject | ExampleObject>;
+    requestBodies?: Record<string, ReferenceObject | RequestBodyObject>;
+    headers?: Record<string, ReferenceObject | HeaderObject>;
+    securitySchemes?: Record<string, ReferenceObject | SecuritySchemeObject>;
+    links?: Record<string, ReferenceObject | LinkObject>;
+    callbacks?: Record<string, ReferenceObject | CallbackObject>;
+}
+interface TagObject {
+    name: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+}
+interface OperationObject {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+    operationId?: string;
+    parameters?: (ReferenceObject | ParameterObject)[];
+    requestBody?: ReferenceObject | RequestBodyObject;
+    responses?: ResponsesObject;
+    callbacks?: Record<string, ReferenceObject | CallbackObject>;
+    deprecated?: boolean;
+    security?: SecurityRequirementObject[];
+    servers?: ServerObject[];
+}
+interface PathItemObject {
+    $ref?: string;
+    summary?: string;
+    description?: string;
+    get?: OperationObject;
+    put?: OperationObject;
+    post?: OperationObject;
+    delete?: OperationObject;
+    options?: OperationObject;
+    head?: OperationObject;
+    patch?: OperationObject;
+    trace?: OperationObject;
+    servers?: ServerObject[];
+    parameters?: (ReferenceObject | ParameterObject)[];
+}
+interface Document {
+    openapi: string;
+    info: InfoObject;
+    servers?: ServerObject[];
+    paths: PathsObject;
+    components?: ComponentsObject;
+    security?: SecurityRequirementObject[];
+    tags?: TagObject[];
+    externalDocs?: ExternalDocumentationObject;
+    'x-express-openapi-additional-middleware'?: (((request: any, response: any, next: any) => Promise<void>) | ((request: any, response: any, next: any) => void))[];
+    'x-express-openapi-validation-strict'?: boolean;
+}
+
+interface CustomActionSchema<T = unknown> {
+    name?: string;
+    rest?: RestSchema | RestSchema[] | string | string[];
+    visibility?: ActionVisibility;
+    service?: Service;
+    cache?: boolean | ActionCacheOptions;
+    handler?: (ctx: Context<never, never>) => Promise<T> | T;
+    tracing?: boolean | TracingActionOptions;
+    bulkhead?: BulkheadOptions;
+    circuitBreaker?: BrokerCircuitBreakerOptions;
+    retryPolicy?: RetryPolicyOptions;
+    fallback?: string | FallbackHandler;
+    hooks?: ActionHooks;
+    params?: unknown;
+    disableTransforms?: boolean;
+    rateLimiter?: string;
+    rateLimiterCountTowardDefault?: boolean;
+    openAPINames?: string[] | null;
+    openapi?: OperationObject;
+    bodySchemaRefName?: string;
+}
+type Alias = {
+    actionName: string;
+    path: string;
+    fullPath: string;
+    methods: string;
+    routePath: string;
+    action: CustomActionSchema;
+};
+
+type ValidationSchema = JSONSchemaType<any>;
+type Transform<T, U> = (val: T) => U;
+type TransformLevel = {
+    type: 'access';
+    key: string;
+} | {
+    type: 'this';
+} | {
+    type: 'loop';
+} | {
+    type: 'select';
+    subTransforms: TransformField[];
+};
+type TransformField = TransformLevel[];
+type TransformMap = WeakMap<ValidationSchema, TransformField[]>;
+interface Transformer<T, U> {
+    transformMap: TransformMap;
+    beforeTransformer: Transform<unknown | T, unknown | U>;
+    afterTransformer: Transform<unknown | U, unknown | T>;
+    findTransforms: (schema: ValidationSchema) => TransformField[];
+}
+
+/**
+ * Use zod for schema validation.
+ * DO NOT support Async refinements/transforms yet.
+ *
+ * Transforms MUST BE handled by the consumer directly.
+ */
+declare class ZodValidator extends Validators.Base {
+    compile(): () => void;
+    validate<S extends ZodType>(params: unknown, schema: S, ctx?: Context): z.output<S>;
+    /**
+     * Override BaseValidator middleware to handle our custom compile function.
+     */
+    middleware(): (handler: ActionHandler, action: ActionSchema) => unknown;
+}
+declare module 'moleculer' {
+    interface BaseValidator {
+        validate<S extends ZodType>(params: unknown, schema: S): z.output<S>;
+    }
+}
+
+/**
+ * Moleculer validator using Ajv/zod for schema validation.
+ *
+ * It also supports some additional features:
+ * - Property transformations depending on the schema (Dates, ObjectIds, array coercion)
+ * - Ref extractor, used to optimize schema compilation, and generate better OpenAPI specs
+ *
+ * Some config can be done at the action level:
+ * - disableTransforms: Disable all transformations for this action
+ * - validatorMode: Use a different validator mode for this action
+ */
+declare class AjvValidator<Mode extends string> extends Validators.Base {
+    private readonly modes;
+    private readonly defaultMode;
+    private readonly broker;
+    readonly zodValidator?: ZodValidator;
+    /**
+     * Cache of compiled validation functions.
+     * This is because compiling a schema is quite expensive for Ajv.
+     */
+    private compiledFns;
+    constructor(opts: Record<Mode, Options>, defaultMode: Mode, zodValidator?: ZodValidator);
+    /**
+     * Validate a set of parameters against a schema.
+     *
+     * May have a small performance hit on the first call for a specific schema,
+     * as it will compile the schema.
+     */
+    validate(params: unknown, schema: ValidationSchema): true;
+    validate<S extends ZodType>(params: unknown, schema: S): z.output<S>;
+    /**
+     * This method compiles a schema into a validation function.
+     *
+     * Compiling a schema is quite expensive, so it will only be done once per schema.
+     */
+    compile(schema: ValidationSchema, mode?: Mode): (params: unknown, ctx?: Context) => boolean;
+    /**
+     * For debugging purposes, log the validation errors.
+     * This is only enabled if the DETAILED_AJV_VALIDATION_ERRORS env var is set to 'yes'.
+     */
+    logError(name: string, schema: ValidationSchema, errors?: null | ErrorObject[]): void;
+    /**
+     * We wrap the localAction and localEvent methods to add validation to the actions and events handlers.
+     * Note that we lazy compile schemas in order to avoid a performance hit on startup.
+     */
+    middleware(): (handler: ActionHandler, action: ActionSchema) => unknown;
+}
+declare module 'moleculer' {
+    interface BaseValidator {
+        validate(params: unknown, schema: ValidationSchema): true;
+    }
+}
+
+type Unpacked<T> = T extends (infer U)[] ? U : never;
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+type OptionallyArray<T> = T | T[];
+
+type ServiceEventSchema = ServiceEvent & {
+    params?: unknown;
+};
+
+/**
+ * This type represent what is accessible from the `this` in a service file.
+ */
+type ServiceThis<Settings, Methods, Mixins, AdditionalProperties> = {
+    actions: never;
+    settings: Settings;
+} & Methods & AdditionalProperties & Service & UnionToIntersection<Unpacked<Mixins>>['methods'] & Record<string | symbol, unknown>;
+/**
+ * Type used for injecting `this` in an object.
+ */
+type ObjectServiceThis<T, Settings, Methods, Mixins, AdditionalProperties> = T & ThisType<ServiceThis<Settings, Methods, Mixins, AdditionalProperties>>;
+/**
+ * Type used for injecting `this` in a simple function.
+ */
+type CallbackServiceThis<Return, Settings, Methods, Mixins, AdditionalProperties, Parameters extends unknown[] = []> = (this: ServiceThis<Settings, Methods, Mixins, AdditionalProperties>, ...params: Parameters) => Return;
+interface CustomServiceSchema<Settings, Methods, Mixins, AdditionalProperties> {
+    name: string;
+    version?: string | number;
+    dependencies?: OptionallyArray<string | ServiceDependency>;
+    metadata?: Record<string, unknown>;
+    settings?: Settings;
+    hooks?: ServiceHooks;
+    mixins?: Mixins;
+    methods?: ObjectServiceThis<Methods, Settings, Methods, Mixins, AdditionalProperties>;
+    actions?: Record<string, ObjectServiceThis<CustomActionSchema, Settings, Methods, Mixins, AdditionalProperties>>;
+    events?: Record<string, ObjectServiceThis<ServiceEventSchema, Settings, Methods, Mixins, AdditionalProperties>>;
+    created?: OptionallyArray<CallbackServiceThis<void, Settings, Methods, Mixins, AdditionalProperties>>;
+    started?: OptionallyArray<CallbackServiceThis<Promise<void> | void, Settings, Methods, Mixins, AdditionalProperties>>;
+    stopped?: OptionallyArray<CallbackServiceThis<Promise<void> | void, Settings, Methods, Mixins, AdditionalProperties>>;
+    merged?: OptionallyArray<CallbackServiceThis<Promise<void> | void, Settings, Methods, Mixins, AdditionalProperties, [
+        CustomServiceSchema<Settings, Methods, Mixins, AdditionalProperties>
+    ]>>;
+}
+
+/**
+ * This class replace the default Context class in Moleculer to:
+ * - Add a ctx.logger instance with the trace.id and span.id in the bindings
+ */
+declare class ContextFactory<P = unknown, M extends object = {}, L = GenericObject> extends Context<P, M, L> {
+    constructor(broker: ServiceBroker, endpoint: Endpoint);
+    startSpan(name: string, opts?: Moleculer__default.GenericObject): Moleculer__default.Span;
+    /**
+     * Get a logger for this specific span of the context.
+     */
+    setLogger(): void;
+}
+declare module 'moleculer' {
+    interface Context {
+        logger: Moleculer__default.LoggerInstance;
+    }
+}
+
+export { ZodValidator as Z, AjvValidator as d, ContextFactory as i };
+export type { Alias as A, SecuritySchemeObject as B, CustomActionSchema as C, Document as D, ExternalDocumentationObject as E, CallbackObject as F, ComponentsObject as G, HeaderObject as H, InfoObject as I, JSONSchemaType as J, TagObject as K, LicenseObject as L, MediaTypeObject as M, PathItemObject as N, OperationObject as O, PropertiesSchema as P, ReferenceObject as R, SomeJSONSchema as S, Transformer as T, ValidationSchema as V, CustomServiceSchema as a, SchemaObject as b, RequiredMembers as c, Transform as e, TransformLevel as f, TransformMap as g, TransformField as h, ContactObject as j, ServerVariableObject as k, ServerObject as l, PathsObject as m, ParameterObject as n, ParameterBaseObject as o, ExampleObject as p, EncodingObject as q, RequestBodyObject as r, LinkObject as s, ResponseObject as t, ResponsesObject as u, SecurityRequirementObject as v, HttpSecurityScheme as w, ApiKeySecurityScheme as x, OAuth2SecurityScheme as y, OpenIdSecurityScheme as z };