@autofleet/sheilta 2.3.0 → 2.4.1-0

package/lib/index.d.cts

@@ -1,112 +1,609 @@
-import { Handler } from 'express';
-import { LoggerInstanceManager } from '@autofleet/logger';
+import { Model, ModelStatic, Op, Sequelize, WhereOptions, literal } from "sequelize";
+import { Handler, Router } from "express";
+import { LoggerInstanceManager } from "@autofleet/logger";
+import { RedisClientType, createClient } from "redis";
+import rabbit from "@autofleet/rabbit";
+import { z, z as z$1 } from "zod/v3";
+import { EventEmitter } from "node:events";
 
-declare const formatOperators: (Sequelize: any) => {};
+//#region src/operators/index.d.ts
 
+declare const formatOperators: (sequelize?: {
+  Op: typeof Op;
+}) => Record<string, symbol>;
+//#endregion
+//#region src/formatter/jsonAttributesFormater.d.ts
+declare const ComputedActions: {
+  readonly length: "length";
+};
+interface JsonSelectAttribute {
+  columnName: string;
+  keys: string[];
+  alias?: string;
+}
+interface JsonComputedAttribute {
+  columnName: string;
+  action: keyof typeof ComputedActions;
+  alias: string;
+}
+interface JsonAttributes {
+  select?: JsonSelectAttribute[];
+  computed?: JsonComputedAttribute[];
+}
+//#endregion
+//#region src/formatter/index.d.ts
 type OrderItem = string | [string, string];
 type SequelizeOrder = string | OrderItem[];
-type FormatPayloadOptions = {
-    includeRawPayload?: boolean;
-    literalAttributes?: LiteralAttribute[];
-    DBFormatter?: any;
-    skipSearchTermFormat?: boolean;
-    additionalAllowedAttributes?: string[];
-};
-type ConditionWithOperator = {
-    operator: string;
-    value: string;
-};
+interface FormatPayloadOptions {
+  includeRawPayload?: boolean;
+  literalAttributes?: LiteralAttribute[];
+  DBFormatter?: typeof literal;
+  skipSearchTermFormat?: boolean;
+  additionalAllowedAttributes?: string[];
+}
+interface ConditionWithOperator {
+  operator: string;
+  value: string;
+}
 type ConditionValue = ConditionWithOperator | ConditionWithOperator[] | string | string[];
 /**
- * Generates replacements for the given conditions.
- *
- * @param conditions - The conditions to generate replacements for.
- * @returns The replacements object.
- */
+* Generates replacements for the given conditions.
+*
+* @param conditions - The conditions to generate replacements for.
+* @returns The replacements object.
+*/
 declare const generateFilterReplacements: (conditions: Record<string, ConditionValue>) => Record<string, string>;
-declare const formatPayload: ({ order, page, perPage, include, query, attributes, searchTerm, jsonAttributes, }: {
-    order?: any[];
-    page?: number;
-    perPage?: number;
-    include?: any[];
-    query?: {};
-    attributes?: any;
-    searchTerm?: any;
-    jsonAttributes?: {};
-}, model?: any, options?: FormatPayloadOptions) => {
-    externalQueryValues: Record<string, unknown>;
-    attributes: any[] | {
-        include: any[];
-    };
-    query: Record<string, unknown>;
-    order: SequelizeOrder[];
-    page: number;
-    perPage: number;
-    include: any;
-    scopes: (string | {
-        method: (string | {
-            replacementsMap: Record<string, string>;
-            scopeValue: any;
-        })[];
+interface Include {
+  association?: string;
+  model?: string;
+  required?: boolean;
+  include?: Include[];
+}
+interface FormatPayloadData {
+  order?: string[];
+  page?: number;
+  perPage?: number;
+  include?: (string | Include)[];
+  query?: Record<string, unknown>;
+  attributes?: string[] | null;
+  searchTerm?: string | null;
+  jsonAttributes?: JsonAttributes;
+}
+type Literal = ReturnType<typeof literal>;
+interface FormattedPayload {
+  query: Record<string, unknown>;
+  externalQueryValues?: Record<string, unknown>;
+  attributes: (SequelizeOrder | (string | Literal)[])[] | {
+    include: (SequelizeOrder | (string | Literal)[])[];
+  };
+  order: (SequelizeOrder | Literal)[];
+  page: number;
+  perPage: number;
+  include: any;
+  scopes: (string | {
+    method: (string | {
+      replacementsMap: Record<string, string>;
+      scopeValue: any;
     })[];
-};
-
-type literal = any;
-type LiteralQuery = (literal | string)[] | literal;
-type LiteralAttribute = {
-    attribute: string;
-    literal: LiteralQuery;
-};
-type MiddlewareValidationOption = {
-    literalAttributes?: LiteralAttribute[];
-    enrichmentAttributes?: string[];
-    additionalAllowedAttributes?: string[];
-    logger?: LoggerInstanceManager;
-};
-type ReqKeys = 'body' | 'query';
+  })[];
+}
+declare const formatPayload: ({
+  order,
+  page,
+  perPage,
+  include,
+  query,
+  attributes,
+  searchTerm,
+  jsonAttributes
+}: FormatPayloadData, model?: any, options?: FormatPayloadOptions) => FormattedPayload;
+//#endregion
+//#region src/middleware/index.d.ts
+type literal$1 = any;
+type LiteralQuery = (literal$1 | string)[] | literal$1;
+interface LiteralAttribute {
+  attribute: string;
+  literal: LiteralQuery;
+}
+interface MiddlewareValidationOption {
+  literalAttributes?: LiteralAttribute[];
+  enrichmentAttributes?: string[];
+  additionalAllowedAttributes?: string[];
+  logger?: LoggerInstanceManager;
+}
+type ReqKeys = "body" | "query";
 /** consider using @see {@link queryHandler} directly */
 declare const queryValidationMiddleware: (model: any, options?: MiddlewareValidationOption, inner?: ReqKeys) => Handler;
 /** consider using @see {@link queryHandler} directly */
 declare const queryFormatMiddleware: (model: any, options?: FormatPayloadOptions, inner?: ReqKeys) => Handler;
-
-declare const validatePayload: ({ query, order, attributes, include, page, perPage, enrichments, group, jsonAttributes, }: {
-    query?: {};
-    order?: any[];
-    attributes?: any[];
-    include?: any[];
-    page?: number;
-    perPage?: number;
-    enrichments?: any[];
-    group?: any[];
-    jsonAttributes?: {};
-}, model?: any, options?: MiddlewareValidationOption) => boolean;
-
+//#endregion
+//#region src/validations/index.d.ts
+interface PayloadValidationData {
+  query?: object;
+  order?: string[];
+  attributes?: string[];
+  include?: any[];
+  page?: number;
+  perPage?: number;
+  enrichments?: string[] | {
+    [enrichmentName: string]: {
+      exclude?: string[];
+    };
+  };
+  group?: string[];
+  jsonAttributes?: {
+    select?: {
+      columnName: string;
+      keys: string[];
+      alias?: string;
+    }[];
+    computed?: {
+      columnName: string;
+      action: "length";
+      alias: string;
+    }[];
+  };
+}
+declare const validatePayload: ({
+  query,
+  order,
+  attributes,
+  include,
+  page,
+  perPage,
+  enrichments,
+  group,
+  jsonAttributes
+}: PayloadValidationData, model?: any, options?: MiddlewareValidationOption) => boolean;
+//#endregion
+//#region src/handler/index.d.ts
 interface QueryValues extends ReturnType<typeof formatPayload> {
-    enrichments?: string[] | Record<string, {
-        exclude: string[];
-    }>;
-    distinct: boolean;
+  enrichments?: string[] | Record<string, {
+    exclude: string[];
+  }>;
+  distinct: boolean;
+  searchTerm?: string;
 }
 interface QueryHandlerOptions {
-    /** The sequelize model too which querying abilities are added. */
-    model: any;
-    /** Optional settings for validation. */
-    validationOptions?: Omit<MiddlewareValidationOption, 'logger'>;
-    /** Optional settings for payload formatting */
-    formatOptions?: FormatPayloadOptions;
-    logger: LoggerInstanceManager;
-    /** The name of model to be printed in logs. defaults to `model`s constructor name. */
-    modelName?: string;
-    /** Sequelize scopes of the model to be used within the query. @example ['userScope'] */
-    additionalScopes?: string[];
-    /** Callback to allow modifying the query values prior to querying the DB */
-    modifyQueryValues?: (queryValues: QueryValues) => QueryValues;
-    /** Optional callback to modify endpoint's response based on the DBs response. */
-    onRowsRetrieved?: (data: {
-        rows: any[];
-        count: number;
-    }, queryValues: QueryValues) => any;
-}
-declare const queryHandler: ({ model, logger, validationOptions, formatOptions, modelName, additionalScopes, modifyQueryValues, onRowsRetrieved, }: QueryHandlerOptions) => Handler;
-
-export { type LiteralAttribute, type MiddlewareValidationOption, formatOperators, generateFilterReplacements, queryFormatMiddleware, queryHandler, queryValidationMiddleware, validatePayload };
+  /** The sequelize model too which querying abilities are added. */
+  model: any;
+  /** Optional settings for validation. */
+  validationOptions?: Omit<MiddlewareValidationOption, "logger">;
+  /** Optional settings for payload formatting */
+  formatOptions?: FormatPayloadOptions;
+  logger: LoggerInstanceManager;
+  /** The name of model to be printed in logs. defaults to `model`s constructor name. */
+  modelName?: string;
+  /** Sequelize scopes of the model to be used within the query. @example ['userScope'] */
+  additionalScopes?: string[];
+  /** Callback to allow modifying the query values prior to querying the DB */
+  modifyQueryValues?: (queryValues: QueryValues) => QueryValues;
+  /** Optional callback to modify endpoint's response based on the DBs response. */
+  onRowsRetrieved?: (data: {
+    rows: any[];
+    count: number;
+  }, queryValues: QueryValues) => any;
+}
+type Asyncify$1<T extends (...a: any[]) => any> = (...a: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+declare const queryHandler: ({
+  model,
+  logger,
+  validationOptions,
+  formatOptions,
+  modelName,
+  additionalScopes,
+  modifyQueryValues,
+  onRowsRetrieved
+}: QueryHandlerOptions) => Asyncify$1<Handler>;
+//#endregion
+//#region src/bulker/src/types.d.ts
+type Id = string | number;
+interface JobMetadata {
+  status: string;
+  total: number;
+  action: string;
+}
+interface ConsumeOptions {
+  enableRabbitTrace?: boolean;
+  [key: string]: any;
+}
+interface JobStatus {
+  jobId: string;
+  status: string;
+  action: string;
+  total: number;
+  queued: number;
+  processed: number;
+  succeeded: number;
+  failed: number;
+  errors: any[];
+  createdAt?: string;
+  updatedAt?: string;
+  duration: {
+    startTime: string | null;
+    endTime: string | null;
+    durationMs: number | null;
+  };
+}
+type MessageAck = () => Promise<void>;
+type MessageNack = (err?: Error, requeue?: boolean) => Promise<void>;
+type BulkPerIdHandler<T = any> = (args: {
+  jobId?: string;
+  id: Id;
+  payload: T;
+}, ack: MessageAck, nack: MessageNack) => Promise<void>;
+interface AdditionalIdsHookData<T = any> {
+  rawPayload: {
+    query: Record<string, any>;
+    include?: any[];
+    searchTerm: string;
+  };
+  payload: T;
+}
+interface BulkRouteOptions<T = any> {
+  /** e.g. "change-state" - the action identifier sent in request body */
+  action: string;
+  /** Sequelize model from which to scan IDs */
+  model: Model<any, any> | ModelStatic<any> | any;
+  modelScopes: string[];
+  /** Per-ID handler that performs the operation */
+  consumer: BulkPerIdHandler<T>;
+  consumerOptions?: ConsumeOptions;
+  rabbitQueueName?: string;
+  payloadSchema?: z$1.ZodType<T>;
+  /** Identity Scopes to be provided and are used and validated from the query.query object */
+  identityScopes?: string[];
+  queryFunction?: (reqBody: any) => Promise<Record<string, any>[]>;
+  idField?: string;
+  pageSize?: number;
+  workerConcurrency?: number;
+  jobAttempts?: number;
+  jobBackoffMs?: number;
+  removeOnComplete?: boolean | number;
+  removeOnFail?: boolean | number;
+  /** Inject tenant/RBAC filters (AND-ed with user query) */
+  contextWhere?: (payload: T) => WhereOptions;
+  /**
+  * Hook to provide additional IDs that will be OR-ed with the main query.
+  * This is useful when you need to manually fetch additional IDs based on the raw request body.
+  * The returned IDs will be included in the where clause using an OR statement.
+  *
+  * @example
+  * additionalIdsHook: async (data) => {
+  *   const { rawPayload, payload } = reqBody;
+  *   if (!rawPayload.searchTerm) return [];
+  *   const filters = rawPayload?.query?.fleetId ? { fleetId: query.query.fleetId } : {};
+  *   const labelIds = await searchDriversByLabelsValue(rawPayload.searchTerm, filters);
+  *   const vendorIds = await searchDriversByVendorName(rawPayload.searchTerm, filters);
+  *   return [...labelIds, ...vendorIds];
+  * }
+  */
+  additionalIdsHook?: (data: AdditionalIdsHookData) => Promise<Id[]>;
+}
+interface BulkRouterEvents {
+  "job:created": (data: {
+    jobId: string;
+    action: string;
+    total: number;
+  }) => void;
+  "job:started": (data: {
+    jobId: string;
+    action: string;
+  }) => void;
+  "job:queued": (data: {
+    jobId: string;
+    action: string;
+    queued: number;
+    total: number;
+  }) => void;
+  "job:completed": (data: {
+    jobId: string;
+    action: string;
+    processed: number;
+    failed: number;
+    duration: number;
+  }) => void;
+  "job:canceled": (data: {
+    jobId: string;
+    action: string;
+  }) => void;
+  "job:failed": (data: {
+    jobId: string;
+    action: string;
+    error: string;
+  }) => void;
+  "item:processing": (data: {
+    jobId: string;
+    action: string;
+    id: string | number;
+  }) => void;
+  "item:processed": (data: {
+    jobId: string;
+    action: string;
+    id: string | number;
+  }) => void;
+  "item:failed": (data: {
+    jobId: string;
+    action: string;
+    id: string | number;
+    error: string;
+  }) => void;
+  "item:retrying": (data: {
+    jobId: string;
+    action: string;
+    id: string | number;
+  }) => void;
+  "worker:started": (data: {
+    action: string;
+    queueName: string;
+  }) => void;
+  "worker:error": (data: {
+    action: string;
+    error: string;
+  }) => void;
+  "scan:page": (data: {
+    jobId: string;
+    action: string;
+    pageNumber: number;
+    itemsInPage: number;
+  }) => void;
+}
+/**
+* Interface for event emitters with the emitEvent helper method
+*/
+interface IBulkEventEmitter {
+  emitEvent<K extends keyof BulkRouterEvents>(event: K, ...args: Parameters<BulkRouterEvents[K]>): void;
+}
+//#endregion
+//#region src/bulker/src/BulkRoute.d.ts
+type Asyncify<T extends (...a: any[]) => any> = (...a: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+declare class BulkRoute<T = any> {
+  private readonly bulker;
+  private readonly opts;
+  readonly action: string;
+  private readonly model;
+  private readonly consumer;
+  private readonly idField;
+  private readonly pageSize;
+  private readonly rabbitQueueName;
+  private readonly rabbit;
+  private readonly consumerOptions;
+  private readonly queryFunction?;
+  private readonly payloadSchema?;
+  private readonly identityScopeSchema;
+  private readonly modelScopes;
+  constructor(bulker: Bulker, opts: BulkRouteOptions<T>);
+  bulkHandler: Asyncify<Handler>;
+  /** Get user jobs - public method for BulkRouter to use */
+  getUserJobs(userId: string, limit?: number): Promise<(JobStatus | null)[]>;
+  private rabbitScanAndEnqueue;
+  startRabbitWorker(): Promise<void>;
+}
+//#endregion
+//#region src/bulker/src/BulkRouter.d.ts
+declare class BulkRouter {
+  private readonly bulker;
+  private readonly router;
+  private routes;
+  private actionsToRouteMap;
+  private staticRoute;
+  constructor(bulker: Bulker, router?: Router, staticRoute?: string);
+  private registerStaticRoutes;
+  addAction<T = any>(actionName: string, opts: Omit<BulkRouteOptions<T>, "action">): BulkRoute<T>;
+  private bulkHandler;
+  private getJobHandler;
+  private cancelJobHandler;
+  private getMyJobsHandler;
+  /** Get the configured router instance */
+  getRouter(): Router;
+}
+//#endregion
+//#region src/bulker/src/events.d.ts
+interface BulkRouterEvents$1 {
+  "job:created": (data: {
+    jobId: string;
+    action: string;
+    total: number;
+  }) => void;
+  "job:started": (data: {
+    jobId: string;
+    action: string;
+  }) => void;
+  "job:queued": (data: {
+    jobId: string;
+    action: string;
+    queued: number;
+    total: number;
+  }) => void;
+  "job:completed": (data: {
+    jobId: string;
+    action: string;
+    processed: number;
+    failed: number;
+    duration: number;
+  }) => void;
+  "job:canceled": (data: {
+    jobId: string;
+    action: string;
+  }) => void;
+  "job:failed": (data: {
+    jobId: string;
+    action: string;
+    error: string;
+  }) => void;
+  "item:processing": (data: {
+    jobId: string;
+    action: string;
+    id: string | number;
+  }) => void;
+  "item:processed": (data: {
+    jobId: string;
+    action: string;
+    id: string | number;
+  }) => void;
+  "item:failed": (data: {
+    jobId: string;
+    action: string;
+    id: string | number;
+    error: string;
+  }) => void;
+  "item:retrying": (data: {
+    jobId: string;
+    action: string;
+    id: string | number;
+  }) => void;
+  "worker:started": (data: {
+    action: string;
+    queueName: string;
+  }) => void;
+  "worker:error": (data: {
+    action: string;
+    error: string;
+  }) => void;
+  "scan:page": (data: {
+    jobId: string;
+    action: string;
+    pageNumber: number;
+    itemsInPage: number;
+  }) => void;
+}
+interface BulkEventEmitter extends EventEmitter {
+  on<K extends keyof BulkRouterEvents$1>(event: K, listener: BulkRouterEvents$1[K]): this;
+  once<K extends keyof BulkRouterEvents$1>(event: K, listener: BulkRouterEvents$1[K]): this;
+  off<K extends keyof BulkRouterEvents$1>(event: K, listener: BulkRouterEvents$1[K]): this;
+  removeListener<K extends keyof BulkRouterEvents$1>(event: K, listener: BulkRouterEvents$1[K]): this;
+  emit<K extends keyof BulkRouterEvents$1>(event: K, ...args: Parameters<BulkRouterEvents$1[K]>): boolean;
+}
+interface EmitsBulkEvents {
+  emitEvent<K extends keyof BulkRouterEvents$1>(event: K, ...args: Parameters<BulkRouterEvents$1[K]>): void;
+}
+//#endregion
+//#region src/bulker/src/JobManager.d.ts
+/**
+* Manages all job-related operations in Redis
+* Centralizes job creation, status updates, cancellation, and user job tracking
+*/
+declare class JobManager {
+  private eventEmitter?;
+  private readonly redis;
+  private readonly defaults;
+  constructor(redis: RedisClientType, defaults?: {
+    maxJobsPerUser?: number;
+    jobTtlSeconds?: number;
+    errorLogLimit?: number;
+  });
+  /** Set event emitter for emitting job events */
+  setEventEmitter(emitter: EmitsBulkEvents): void;
+  /** Generate Redis key for job */
+  static jobKey(jobId: string): string;
+  /** Generate Redis key for user jobs list */
+  static userJobsKey(userId: string): string;
+  /**
+  * Initialize a new job in Redis
+  */
+  initJob(jobId: string, meta: JobMetadata): Promise<void>;
+  /**
+  * Get job status from Redis
+  */
+  getJob(jobId: string): Promise<JobStatus | null>;
+  /**
+  * Set a single field on a job
+  */
+  setJobField(jobId: string, field: string, value: string): Promise<boolean>;
+  /**
+  * Set multiple fields on a job
+  */
+  setJobFields(jobId: string, fields: Record<string, string>): Promise<boolean>;
+  /**
+  * Increment a counter field on a job
+  */
+  incrJobField(jobId: string, field: "queued" | "processed" | "succeeded" | "failed", by?: number): Promise<number>;
+  /**
+  * Get a single field from a job
+  */
+  getJobField(jobId: string, field: string): Promise<string | undefined>;
+  /**
+  * Cancel a job
+  */
+  cancelJob(jobId: string): Promise<boolean>;
+  /**
+  * Mark job as completed (for jobs with no items to process)
+  */
+  completeEmptyJob(jobId: string): Promise<void>;
+  /**
+  * Handle successful message processing (ack)
+  * Uses Redis Lua script for atomic operation
+  */
+  ack(jobId: string): Promise<void>;
+  /**
+  * Handle failed message processing (nack)
+  * Uses Redis Lua script for atomic operation
+  */
+  nack(jobId: string, errorMsg: string, data: any): Promise<void>;
+  /**
+  * Add a job to user's job list
+  */
+  addUserJob(userId: string, jobId: string): Promise<void>;
+  /**
+  * Remove a job from user's job list
+  */
+  removeUserJob(userId: string, jobId: string): Promise<void>;
+  /**
+  * Get all jobs for a user
+  */
+  getUserJobs(userId: string, limit?: number): Promise<(JobStatus | null)[]>;
+}
+//#endregion
+//#region src/bulker/src/Errors.d.ts
+declare class BulkerError extends Error {
+  readonly retryable: boolean;
+  constructor(message: string, retryable?: boolean);
+  static isBulkerError(err: unknown): err is BulkerError;
+  static wrap(err: unknown, message?: string, retryable?: boolean): BulkerError;
+  static retryable(message: string): BulkerError;
+  static nonRetryable(message: string): BulkerError;
+}
+//#endregion
+//#region src/bulker/src/index.d.ts
+interface BulkerInit {
+  sequelize: Sequelize;
+  logger: LoggerInstanceManager;
+  rabbit: rabbit;
+  redis: RedisClientType | ReturnType<typeof createClient> | {
+    host: string;
+    port?: number;
+    password?: string;
+    db?: number;
+  };
+  getUserId?: () => string | null;
+  emitEvents?: boolean;
+  defaults?: {
+    pageSize?: number;
+    maxJobsPerUser?: number;
+    idField?: string;
+    workerConcurrency?: number;
+    jobTtlSeconds?: number;
+    errorLogLimit?: number;
+  };
+}
+declare class Bulker extends EventEmitter implements BulkEventEmitter {
+  readonly sequelize: Sequelize;
+  readonly logger: BulkerInit["logger"];
+  readonly redis: RedisClientType;
+  readonly rabbit: rabbit;
+  readonly defaults: Required<NonNullable<BulkerInit["defaults"]>>;
+  readonly jobManager: JobManager;
+  private readonly bulkRouters;
+  getUserId: BulkerInit["getUserId"];
+  readonly eventsEnabled: boolean;
+  constructor(init: BulkerInit);
+  createBulkRouter(router?: Router, staticRoute?: string): BulkRouter;
+  /**
+  * Emit event only if events are enabled.
+  * Centralizes the eventsEnabled check to avoid repetition.
+  */
+  emitEvent<K extends keyof BulkRouterEvents$1>(event: K, ...args: Parameters<BulkRouterEvents$1[K]>): void;
+}
+//#endregion
+export { type BulkRouteOptions, type BulkRouterEvents, Bulker, BulkerError, JobManager as BulkerJobManager, type IBulkEventEmitter, type JobMetadata, type JobStatus, type LiteralAttribute, type MiddlewareValidationOption, formatOperators, generateFilterReplacements, queryFormatMiddleware, queryHandler, queryValidationMiddleware, validatePayload, z };
+//# sourceMappingURL=index.d.cts.map