glasswork 1.0.0 → 1.1.0

package/dist/jobs/observability/dashboard.d.ts

@@ -0,0 +1,19 @@
+import type { CloudWatchDashboardDefinition, GenerateJobsDashboardOptions, GetJobsInsightsQueriesOptions, JobsInsightsQueries } from './types.js';
+/**
+ * Generate a production-ready AWS CloudWatch Dashboard JSON definition for background jobs.
+ *
+ * Can be deployed via AWS CLI (`aws cloudwatch put-dashboard`), AWS CDK (`CfnDashboard`),
+ * or Terraform (`aws_cloudwatch_dashboard`).
+ *
+ * @param options - Dashboard configuration options (names, widgets, region).
+ * @returns An object with dashboardName and serialized dashboardBody JSON.
+ */
+export declare function generateJobsDashboard(options: GenerateJobsDashboardOptions): CloudWatchDashboardDefinition;
+/**
+ * Returns a set of pre-canned CloudWatch Logs Insights queries for monitoring and troubleshooting jobs.
+ *
+ * @param options - Optional configuration for logGroupName and namespace filter.
+ * @returns Queries for recent failures, slowest jobs, retries, and job tracing.
+ */
+export declare function getJobsInsightsQueries(options?: GetJobsInsightsQueriesOptions): JobsInsightsQueries;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/jobs/observability/dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../../../src/jobs/observability/dashboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,6BAA6B,EAC7B,4BAA4B,EAC5B,6BAA6B,EAC7B,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,6BAA6B,CAqI/B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,6BAAkC,GAC1C,mBAAmB,CAerB"}

package/dist/jobs/observability/dashboard.js

@@ -0,0 +1,144 @@
+/**
+ * Generate a production-ready AWS CloudWatch Dashboard JSON definition for background jobs.
+ *
+ * Can be deployed via AWS CLI (`aws cloudwatch put-dashboard`), AWS CDK (`CfnDashboard`),
+ * or Terraform (`aws_cloudwatch_dashboard`).
+ *
+ * @param options - Dashboard configuration options (names, widgets, region).
+ * @returns An object with dashboardName and serialized dashboardBody JSON.
+ */
+export function generateJobsDashboard(options) {
+    const { dashboardName, namespace = 'Glasswork/Jobs', jobNames = [], periodSeconds = 300, region = 'eu-west-1', logGroupName, } = options;
+    // Widget 1: Throughput (JobCount)
+    const throughputMetrics = jobNames.length > 0
+        ? jobNames.map((name) => [namespace, 'JobCount', 'JobName', name, { stat: 'Sum' }])
+        : [[namespace, 'JobCount', { stat: 'Sum' }]];
+    // Widget 2: Errors (JobErrorCount)
+    const errorMetrics = jobNames.length > 0
+        ? jobNames.map((name) => [
+            namespace,
+            'JobErrorCount',
+            'JobName',
+            name,
+            { stat: 'Sum', color: '#d62728' },
+        ])
+        : [[namespace, 'JobErrorCount', { stat: 'Sum', color: '#d62728' }]];
+    // Widget 3: Duration Percentiles
+    const durationMetrics = [
+        [namespace, 'JobDuration', { stat: 'p50', label: 'Duration p50' }],
+        [namespace, 'JobDuration', { stat: 'p90', label: 'Duration p90' }],
+        [namespace, 'JobDuration', { stat: 'p99', label: 'Duration p99' }],
+    ];
+    // Widget 4: Queue Wait Time
+    const queueWaitMetrics = [
+        [namespace, 'QueueWaitTime', { stat: 'Average', label: 'Avg Queue Wait' }],
+        [namespace, 'QueueWaitTime', { stat: 'Maximum', label: 'Max Queue Wait' }],
+    ];
+    // biome-ignore lint/suspicious/noExplicitAny: CloudWatch Dashboard JSON specification uses dynamic property arrays
+    const widgets = [
+        {
+            type: 'metric',
+            x: 0,
+            y: 0,
+            width: 12,
+            height: 6,
+            properties: {
+                metrics: throughputMetrics,
+                view: 'timeSeries',
+                stacked: true,
+                region,
+                title: 'Background Jobs - Throughput (JobCount)',
+                period: periodSeconds,
+            },
+        },
+        {
+            type: 'metric',
+            x: 12,
+            y: 0,
+            width: 12,
+            height: 6,
+            properties: {
+                metrics: errorMetrics,
+                view: 'timeSeries',
+                stacked: true,
+                region,
+                title: 'Background Jobs - Errors & Failures',
+                period: periodSeconds,
+            },
+        },
+        {
+            type: 'metric',
+            x: 0,
+            y: 6,
+            width: 12,
+            height: 6,
+            properties: {
+                metrics: durationMetrics,
+                view: 'timeSeries',
+                region,
+                title: 'Execution Duration (p50 / p90 / p99)',
+                period: periodSeconds,
+                yAxis: {
+                    left: {
+                        label: 'Milliseconds',
+                    },
+                },
+            },
+        },
+        {
+            type: 'metric',
+            x: 12,
+            y: 6,
+            width: 12,
+            height: 6,
+            properties: {
+                metrics: queueWaitMetrics,
+                view: 'timeSeries',
+                region,
+                title: 'Queue Wait Time (Enqueued to Execution)',
+                period: periodSeconds,
+                yAxis: {
+                    left: {
+                        label: 'Milliseconds',
+                    },
+                },
+            },
+        },
+    ];
+    if (logGroupName) {
+        widgets.push({
+            type: 'log',
+            x: 0,
+            y: 12,
+            width: 24,
+            height: 6,
+            properties: {
+                query: `SOURCE '${logGroupName}' | fields @timestamp, JobName, JobId, AttemptNumber, ErrorName, ErrorMessage\n| filter Status in ["failed", "dead_letter"]\n| sort @timestamp desc\n| limit 25`,
+                region,
+                title: 'Recent Job Failures & Dead Letters',
+                view: 'table',
+            },
+        });
+    }
+    return {
+        dashboardName,
+        dashboardBody: JSON.stringify({ widgets }),
+    };
+}
+/**
+ * Returns a set of pre-canned CloudWatch Logs Insights queries for monitoring and troubleshooting jobs.
+ *
+ * @param options - Optional configuration for logGroupName and namespace filter.
+ * @returns Queries for recent failures, slowest jobs, retries, and job tracing.
+ */
+export function getJobsInsightsQueries(options = {}) {
+    const sourcePrefix = options.logGroupName ? `SOURCE '${options.logGroupName}' | ` : '';
+    return {
+        recentFailures: `${sourcePrefix}fields @timestamp, JobName, JobId, AttemptNumber, ErrorName, ErrorMessage\n| filter Status in ["failed", "dead_letter"]\n| sort @timestamp desc\n| limit 50`,
+        slowestJobs: `${sourcePrefix}fields @timestamp, JobName, JobId, JobDuration, QueueWaitTime\n| filter Status = "success"\n| sort JobDuration desc\n| limit 25`,
+        retriedJobs: `${sourcePrefix}fields @timestamp, JobName, JobId, AttemptNumber, Status, ErrorMessage\n| filter AttemptNumber > 1\n| sort @timestamp desc\n| limit 50`,
+        throughputHourly: `${sourcePrefix}filter ispresent(JobName)\n| stats count(*) as Total, sum(JobErrorCount) as Errors, avg(JobDuration) as AvgDurationMs by bin(1h), JobName`,
+        traceJob: (jobId) => `${sourcePrefix}fields @timestamp, JobName, Status, AttemptNumber, @message\n| filter JobId = "${jobId}"\n| sort @timestamp asc`,
+    };
+}
+//# sourceMappingURL=dashboard.js.map

package/dist/jobs/observability/dashboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.js","sourceRoot":"","sources":["../../../src/jobs/observability/dashboard.ts"],"names":[],"mappings":"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"}

package/dist/jobs/observability/emf.d.ts

@@ -0,0 +1,24 @@
+import type { EMFJobMetricRecord, JobExecutionMetricData, JobMetricsConfig } from './types.js';
+/**
+ * Build a structured AWS CloudWatch Embedded Metric Format (EMF) record for a background job.
+ *
+ * Conforms to the AWS CloudWatch EMF specification:
+ * https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html
+ *
+ * @param data - Execution metrics for the completed or failed job.
+ * @param config - Optional configuration for namespace, dimensions, etc.
+ * @returns An object adhering to the EMF JSON schema.
+ */
+export declare function createEMFJobMetric(data: JobExecutionMetricData, config?: JobMetricsConfig): EMFJobMetricRecord;
+/**
+ * Emit an EMF metric to stdout or a configured sink.
+ *
+ * When emitted to stdout within an AWS Lambda environment, AWS CloudWatch Logs automatically
+ * extracts these metrics into CloudWatch Metrics with zero API overhead and zero latency.
+ *
+ * @param data - Execution metrics for the job.
+ * @param config - Optional configuration for namespace, dimensions, or custom sink.
+ * @returns The generated record or null if metrics are disabled.
+ */
+export declare function emitJobMetric(data: JobExecutionMetricData, config?: JobMetricsConfig): EMFJobMetricRecord | null;
+//# sourceMappingURL=emf.d.ts.map

package/dist/jobs/observability/emf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emf.d.ts","sourceRoot":"","sources":["../../../src/jobs/observability/emf.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE/F;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,sBAAsB,EAC5B,MAAM,CAAC,EAAE,gBAAgB,GACxB,kBAAkB,CAyEpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,sBAAsB,EAC5B,MAAM,CAAC,EAAE,gBAAgB,GACxB,kBAAkB,GAAG,IAAI,CAgB3B"}

package/dist/jobs/observability/emf.js

@@ -0,0 +1,100 @@
+import { isTest } from '../../utils/environment.js';
+/**
+ * Build a structured AWS CloudWatch Embedded Metric Format (EMF) record for a background job.
+ *
+ * Conforms to the AWS CloudWatch EMF specification:
+ * https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html
+ *
+ * @param data - Execution metrics for the completed or failed job.
+ * @param config - Optional configuration for namespace, dimensions, etc.
+ * @returns An object adhering to the EMF JSON schema.
+ */
+export function createEMFJobMetric(data, config) {
+    const namespace = config?.namespace ?? 'Glasswork/Jobs';
+    const customDimensions = {
+        ...(config?.dimensions ?? {}),
+        ...(data.customDimensions ?? {}),
+    };
+    const customDimensionKeys = Object.keys(customDimensions);
+    // Standard dimension sets:
+    // 1. [JobName]
+    // 2. [JobName, Status]
+    // 3. [Status]
+    // If custom dimensions exist, they are appended to each dimension set for granular filtering.
+    const baseDimensionSets = [['JobName'], ['JobName', 'Status'], ['Status']];
+    const dimensionSets = customDimensionKeys.length > 0
+        ? baseDimensionSets.map((set) => [...set, ...customDimensionKeys])
+        : baseDimensionSets;
+    const queueWaitTime = data.enqueuedAt
+        ? Math.max(0, data.startedAt.getTime() - data.enqueuedAt.getTime())
+        : undefined;
+    const retryCount = Math.max(0, data.attemptNumber - 1);
+    const isError = data.status !== 'success';
+    const metrics = [
+        { Name: 'JobCount', Unit: 'Count' },
+        { Name: 'JobDuration', Unit: 'Milliseconds' },
+        { Name: 'JobErrorCount', Unit: 'Count' },
+        { Name: 'RetryCount', Unit: 'Count' },
+    ];
+    if (queueWaitTime !== undefined) {
+        metrics.push({ Name: 'QueueWaitTime', Unit: 'Milliseconds' });
+    }
+    const record = {
+        _aws: {
+            Timestamp: Date.now(),
+            CloudWatchMetrics: [
+                {
+                    Namespace: namespace,
+                    Dimensions: dimensionSets,
+                    Metrics: metrics,
+                },
+            ],
+        },
+        JobName: data.jobName,
+        Status: data.status,
+        JobId: data.jobId,
+        AttemptNumber: data.attemptNumber,
+        JobCount: 1,
+        JobDuration: data.durationMs,
+        JobErrorCount: isError ? 1 : 0,
+        RetryCount: retryCount,
+        ...customDimensions,
+    };
+    if (queueWaitTime !== undefined) {
+        record.QueueWaitTime = queueWaitTime;
+    }
+    if (data.error) {
+        record.ErrorName = data.error.name || 'Error';
+        record.ErrorMessage = data.error.message;
+        if (data.error.stack) {
+            record.ErrorStack = data.error.stack;
+        }
+    }
+    return record;
+}
+/**
+ * Emit an EMF metric to stdout or a configured sink.
+ *
+ * When emitted to stdout within an AWS Lambda environment, AWS CloudWatch Logs automatically
+ * extracts these metrics into CloudWatch Metrics with zero API overhead and zero latency.
+ *
+ * @param data - Execution metrics for the job.
+ * @param config - Optional configuration for namespace, dimensions, or custom sink.
+ * @returns The generated record or null if metrics are disabled.
+ */
+export function emitJobMetric(data, config) {
+    const isEnabled = config?.enabled ?? (config?.sink !== undefined || !isTest());
+    if (!isEnabled) {
+        return null;
+    }
+    const record = createEMFJobMetric(data, config);
+    const json = JSON.stringify(record);
+    if (config?.sink) {
+        config.sink(json);
+    }
+    else {
+        console.log(json);
+    }
+    return record;
+}
+//# sourceMappingURL=emf.js.map

package/dist/jobs/observability/emf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emf.js","sourceRoot":"","sources":["../../../src/jobs/observability/emf.ts"],"names":[],"mappings":"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"}

package/dist/jobs/observability/index.d.ts

@@ -0,0 +1,5 @@
+export { createJobsObservabilityClient, type JobsObservabilityClient, } from './client.js';
+export { generateJobsDashboard, getJobsInsightsQueries, } from './dashboard.js';
+export { createEMFJobMetric, emitJobMetric, } from './emf.js';
+export type { CloudWatchDashboardDefinition, EMFJobMetricRecord, EMFMetadata, EMFMetricUnit, FailedJobDTO, GenerateJobsDashboardOptions, GetFailedJobsOptions, GetJobSummaryOptions, GetJobsInsightsQueriesOptions, JobExecutionMetricData, JobExecutionStatus, JobMetricsConfig, JobStatsSummaryDTO, JobsInsightsQueries, JobsObservabilityClientOptions, JobTypeStatsDTO, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/jobs/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/jobs/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,kBAAkB,EAClB,aAAa,GACd,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,6BAA6B,EAC7B,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,4BAA4B,EAC5B,oBAAoB,EACpB,oBAAoB,EACpB,6BAA6B,EAC7B,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,8BAA8B,EAC9B,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/jobs/observability/index.js

@@ -0,0 +1,4 @@
+export { createJobsObservabilityClient, } from './client.js';
+export { generateJobsDashboard, getJobsInsightsQueries, } from './dashboard.js';
+export { createEMFJobMetric, emitJobMetric, } from './emf.js';
+//# sourceMappingURL=index.js.map

package/dist/jobs/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/jobs/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,GAE9B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,kBAAkB,EAClB,aAAa,GACd,MAAM,UAAU,CAAC"}

package/dist/jobs/observability/types.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Lifecycle status of a background job execution for observability metrics.
+ */
+export type JobExecutionStatus = 'success' | 'failed' | 'retry' | 'dead_letter';
+/**
+ * Metric units supported by AWS CloudWatch EMF.
+ */
+export type EMFMetricUnit = 'Count' | 'Milliseconds' | 'Bytes' | 'Seconds' | 'None';
+/**
+ * AWS CloudWatch Embedded Metric Format (EMF) metadata definition.
+ */
+export interface EMFMetadata {
+    Timestamp: number;
+    CloudWatchMetrics: Array<{
+        Namespace: string;
+        Dimensions: string[][];
+        Metrics: Array<{
+            Name: string;
+            Unit: EMFMetricUnit;
+        }>;
+    }>;
+}
+/**
+ * Complete EMF JSON record structure emitted to stdout.
+ */
+export interface EMFJobMetricRecord {
+    _aws: EMFMetadata;
+    JobName: string;
+    Status: JobExecutionStatus;
+    JobId: string;
+    AttemptNumber: number;
+    JobCount: number;
+    JobDuration: number;
+    JobErrorCount: number;
+    QueueWaitTime?: number;
+    RetryCount: number;
+    ErrorName?: string;
+    ErrorMessage?: string;
+    ErrorStack?: string;
+    [key: string]: unknown;
+}
+/**
+ * Input data provided to create an EMF metric record.
+ */
+export interface JobExecutionMetricData {
+    jobName: string;
+    jobId: string;
+    status: JobExecutionStatus;
+    attemptNumber: number;
+    durationMs: number;
+    enqueuedAt?: Date;
+    startedAt: Date;
+    error?: Error;
+    customDimensions?: Record<string, string>;
+}
+/**
+ * Configuration for worker EMF metric emission.
+ */
+export interface JobMetricsConfig {
+    /**
+     * Whether EMF metric logging is enabled.
+     * Defaults to true if not in test environment.
+     */
+    enabled?: boolean;
+    /**
+     * CloudWatch metrics namespace.
+     * @default 'Glasswork/Jobs'
+     */
+    namespace?: string;
+    /**
+     * Additional global dimensions to attach to all job metrics (e.g. environment: 'production').
+     */
+    dimensions?: Record<string, string>;
+    /**
+     * Custom output sink for EMF formatted JSON strings.
+     * Defaults to process.stdout.write / console.log.
+     */
+    sink?: (logLine: string) => void;
+}
+/**
+ * Performance and throughput statistics for a specific job type.
+ */
+export interface JobTypeStatsDTO {
+    jobName: string;
+    count: number;
+    succeededCount: number;
+    failedCount: number;
+    retryCount: number;
+    avgDurationMs: number;
+    p95DurationMs: number;
+}
+/**
+ * Aggregated summary DTO of background jobs across a given time window.
+ */
+export interface JobStatsSummaryDTO {
+    totalExecuted: number;
+    totalSucceeded: number;
+    totalFailed: number;
+    totalRetried: number;
+    /** Success percentage between 0 and 100, rounded to 2 decimals */
+    successRate: number;
+    avgDurationMs: number;
+    p95DurationMs: number;
+    byJob: Record<string, JobTypeStatsDTO>;
+}
+/**
+ * Details of a failed background job execution.
+ */
+export interface FailedJobDTO {
+    jobId: string;
+    jobName: string;
+    attemptNumber: number;
+    errorMessage: string;
+    errorName?: string;
+    errorStack?: string;
+    failedAt: Date;
+    durationMs?: number;
+    queueWaitTimeMs?: number;
+}
+/**
+ * Options for generating a CloudWatch Dashboard.
+ */
+export interface GenerateJobsDashboardOptions {
+    /**
+     * Dashboard name in AWS CloudWatch.
+     */
+    dashboardName: string;
+    /**
+     * Metric namespace.
+     * @default 'Glasswork/Jobs'
+     */
+    namespace?: string;
+    /**
+     * Known job names to generate dedicated graphs and widgets for.
+     */
+    jobNames?: string[];
+    /**
+     * Aggregation period in seconds for CloudWatch widgets.
+     * @default 300 (5 minutes)
+     */
+    periodSeconds?: number;
+    /**
+     * AWS Region for CloudWatch widgets.
+     * @default 'eu-west-1'
+     */
+    region?: string;
+    /**
+     * CloudWatch Log Group name where worker logs are stored.
+     * If provided, an embedded CloudWatch Logs Insights widget will be added.
+     */
+    logGroupName?: string;
+}
+/**
+ * CloudWatch Dashboard JSON definition compatible with AWS API / CLI / CDK / Terraform.
+ */
+export interface CloudWatchDashboardDefinition {
+    dashboardName: string;
+    dashboardBody: string;
+}
+/**
+ * Options for generating CloudWatch Logs Insights queries.
+ */
+export interface GetJobsInsightsQueriesOptions {
+    /**
+     * Target log group name.
+     */
+    logGroupName?: string;
+    /**
+     * Custom namespace if filtered in logs.
+     * @default 'Glasswork/Jobs'
+     */
+    namespace?: string;
+}
+/**
+ * Collection of pre-canned CloudWatch Logs Insights queries.
+ */
+export interface JobsInsightsQueries {
+    /** Query returning recent failed and dead-letter jobs with error messages */
+    recentFailures: string;
+    /** Query finding the slowest job executions */
+    slowestJobs: string;
+    /** Query finding jobs that required retries */
+    retriedJobs: string;
+    /** Hourly job volume and error aggregation */
+    throughputHourly: string;
+    /** Function returning a query to trace a single jobId */
+    traceJob: (jobId: string) => string;
+}
+/**
+ * Options for initializing the JobsObservabilityClient.
+ */
+export interface JobsObservabilityClientOptions {
+    /**
+     * CloudWatch metric namespace.
+     * @default 'Glasswork/Jobs'
+     */
+    namespace?: string;
+    /**
+     * CloudWatch Log Group name for worker execution logs.
+     */
+    logGroupName?: string;
+    /**
+     * AWS Region.
+     */
+    region?: string;
+    /**
+     * Pre-configured CloudWatch client (avoids loading AWS SDK if injected).
+     */
+    cloudWatchClient?: unknown;
+    /**
+     * Pre-configured CloudWatch Logs client (avoids loading AWS SDK if injected).
+     */
+    cloudWatchLogsClient?: unknown;
+}
+/**
+ * Query options for job summaries.
+ */
+export interface GetJobSummaryOptions {
+    startTime?: Date;
+    endTime?: Date;
+    jobNames?: string[];
+    /** Relative hours if startTime/endTime are omitted */
+    hours?: number;
+}
+/**
+ * Query options for fetching failed jobs.
+ */
+export interface GetFailedJobsOptions {
+    startTime?: Date;
+    endTime?: Date;
+    limit?: number;
+    jobName?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/jobs/observability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/jobs/observability/types.ts"],"names":[],"mappings":"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"}

package/dist/jobs/observability/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jobs/observability/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/jobs/observability/types.ts"],"names":[],"mappings":""}

package/dist/jobs/worker.d.ts

@@ -28,8 +28,8 @@ export declare function bootstrapWorker(config: WorkerConfig): (event: SQSEvent
     batchItemFailures: import("aws-lambda").SQSBatchItemFailure[];
     success?: undefined;
 } | {
-    success: boolean;
     batchItemFailures?: undefined;
+    success: boolean;
 }>;
 export {};
 //# sourceMappingURL=worker.d.ts.map

package/dist/jobs/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/jobs/worker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAoB,QAAQ,EAAa,MAAM,YAAY,CAAC;AAQnG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAQ/D,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,YAAY,CAAC;AAmB1D,UAAU,WAAW;IACnB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjF,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7F,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClG;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,IAAI,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AASD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,IAKhD,OAAO,QAAQ,GAAG,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7E,MAAM,OAAO;;;;;;GA8ChB"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/jobs/worker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAoB,QAAQ,EAAa,MAAM,YAAY,CAAC;AAQnG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAQ/D,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,YAAY,CAAC;AAmB1D,UAAU,WAAW;IACnB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjF,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7F,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClG;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,IAAI,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AASD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,WAKzC,QAAQ,GAAG,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QACvE,OAAO;;;;;;GA8ChB"}

package/dist/list-query/builder.d.ts

@@ -1,6 +1,9 @@
 import type { Context } from 'hono';
 import type { BaseIssue, BaseSchema, InferOutput } from 'valibot';
-import type { AggregationConfig, AggregationResult, RawQueryParams, SearchFieldInput } from './types.js';
+import { type FilterMappings } from './filter-mapping.js';
+import type { ListQueryParams } from './query-schema.js';
+import { type SortMappings } from './sort-mapping.js';
+import type { AggregationConfig, AggregationResult, SearchFieldInput } from './types.js';
 import { permissiveOrderByEntrySchema, unrestrictedWhereSchema } from './unrestricted-schemas.js';
 import type { SchemaValidationConfig, ValidatedListParams } from './validator.js';
 export interface PaginatedResult<T> {
@@ -15,6 +18,10 @@ export interface ListQueryConfig<TWhereSchema extends BaseSchema<unknown, unknow
     readonly aggregations?: Record<string, AggregationConfig>;
     /** Applied when the request has no `sorts` query parameter. */
     readonly defaultOrderBy?: readonly InferOutput<TOrderBySchema>[];
+    /** Virtual filter mappers to transform custom filters to database conditions. */
+    readonly mapFilters?: FilterMappings;
+    /** Sorter mappings to transform public sort fields to database/relation paths. */
+    readonly mapSorts?: SortMappings;
 }
 export declare class ListQueryBuilder<TWhereSchema extends BaseSchema<unknown, unknown, BaseIssue<unknown>>, TOrderBySchema extends BaseSchema<unknown, unknown, BaseIssue<unknown>>, TParams extends ValidatedListParams<TWhereSchema, TOrderBySchema> = ValidatedListParams<TWhereSchema, TOrderBySchema>> {
     private config;
@@ -26,7 +33,7 @@ export declare class ListQueryBuilder<TWhereSchema extends BaseSchema<unknown, u
     private whereConditions;
     private transformFn?;
     constructor(config: ListQueryConfig<TWhereSchema, TOrderBySchema>, validationConfig?: SchemaValidationConfig<TWhereSchema, TOrderBySchema> | undefined);
-    parse(query: RawQueryParams, context?: Context): this;
+    parse(query: ListQueryParams, context?: Context): this;
     scope(conditions: InferOutput<TWhereSchema> | Record<string, unknown>): this;
     paginate(): this;
     /**
@@ -36,6 +43,7 @@ export declare class ListQueryBuilder<TWhereSchema extends BaseSchema<unknown, u
     disablePagination(): this;
     transform<TNext extends ValidatedListParams<TWhereSchema, TOrderBySchema>>(fn: (params: ValidatedListParams<TWhereSchema, TOrderBySchema>) => TNext): ListQueryBuilder<TWhereSchema, TOrderBySchema, TNext>;
     build(): TParams;
+    private resolveProcessedOrderBy;
     private buildAggregationParams;
     private removeFieldFromWhere;
     private processLogicalArray;
@@ -62,6 +70,7 @@ export declare function createListQuery<const TConfig extends {
     readonly search?: readonly SearchFieldInput[];
     readonly aggregations?: Record<string, AggregationConfig>;
     readonly defaultOrderBy?: readonly unknown[];
+    readonly mapFilters?: FilterMappings;
 } & ({
     readonly filter: AnySchema;
 } | {