observability-toolkit 1.8.5 → 2.1.0

package/dist/lib/core/shared-schemas.js

@@ -0,0 +1,222 @@
+/**
+ * Shared Zod schemas for common tool parameters
+ * Reduces token usage by centralizing repeated definitions
+ *
+ * ## Overriding Schema Properties
+ *
+ * To customize a shared schema for a specific tool, spread the schema and override:
+ *
+ * @example
+ * ```typescript
+ * // Override limit default and description
+ * const myToolSchema = z.object({
+ *   ...paginationSchema,
+ *   limit: z.number().max(500).default(25).describe('Custom limit (max 500)'),
+ * });
+ *
+ * // Add extra validation to a field
+ * const strictSessionSchema = z.object({
+ *   ...sessionSchema,
+ *   sessionId: z.string().max(64).regex(/^[a-zA-Z0-9-]+$/).optional(),
+ * });
+ * ```
+ *
+ * Later properties in the spread override earlier ones, so tool-specific
+ * schemas always take precedence over shared defaults.
+ */
+import { z } from 'zod';
+import { DEFAULT_LIMIT } from './input-validator.js';
+import { BITS } from './units.js';
+import { normalizeOtelLogSeverity, SPAN_KIND } from './constants-otel.js';
+import { MAX_EXPORT_LIMIT, MAX_QUERY_LIMIT, MAX_SESSION_ID_LENGTH, MAX_SHORT_ID_LENGTH, OTLP_SPAN_ID_LENGTH, OTLP_TRACE_ID_LENGTH, } from './constants.js';
+export const METRICS_DEFAULT_LIMIT = 100;
+export const scoreUnitSchema = z.string().toLowerCase().trim();
+/**
+ * OTel gen_ai.evaluation.score.value — double, finite, unbounded.
+ * Bounds (0-1, 0-100) are evaluator-defined; use scoreUnit to interpret.
+ */
+export const scoreValueSchema = z.number().finite();
+/** Bounded 0–1 score (precision, recall, F1, confidence, thresholds). */
+export const normalizedScoreSchema = z.number().min(0).max(1);
+/** Severity schema for stored data — normalizes aliases and casing at parse time. */
+export const severitySchema = z.string().transform(v => normalizeOtelLogSeverity(v) ?? v);
+/** Severity schema for query inputs — uppercases for case-insensitive matching. */
+export const severityQuerySchema = z.string().min(1).toUpperCase();
+/** OTel span kind — resolved string name for stored/queried data. */
+export const spanKindSchema = z.enum(['INTERNAL', 'SERVER', 'CLIENT', 'PRODUCER', 'CONSUMER']);
+/** OTel span kind — OTLP numeric wire value (0=UNSPECIFIED, 1=INTERNAL .. 5=CONSUMER). */
+export const spanKindNumericSchema = z.int().min(SPAN_KIND.UNSPECIFIED).max(SPAN_KIND.CONSUMER);
+export const evaluatorTypeSchema = z.enum(['llm', 'human', 'rule', 'classifier', 'seed', 'canary']);
+export const genAIOperationNameSchema = z.enum([
+    'chat',
+    'embeddings',
+    'invoke_agent',
+    'execute_tool',
+    'text_completion',
+    'generate_content',
+    'retrieval',
+    'create_agent',
+    'invoke_workflow',
+]);
+export const genAIOutputTypeSchema = z.enum(['text', 'json', 'image', 'speech']);
+export const evaluationAggregationSchema = z.enum(['avg', 'min', 'max', 'count', 'p50', 'p95', 'p99']);
+export const evaluationGroupByFieldSchema = z.enum(['evaluationName', 'scoreLabel', 'evaluator']);
+export const metricAggregationSchema = z.enum(['sum', 'avg', 'min', 'max', 'count', 'p50', 'p95', 'p99', 'rate']);
+export const TraceIdSchema = z
+    .string()
+    .length(OTLP_TRACE_ID_LENGTH, `Trace ID must be ${OTLP_TRACE_ID_LENGTH} characters`)
+    .regex(/^[0-9a-f]+$/, 'Trace ID must be lowercase hexadecimal')
+    .refine((val) => !(/^0+$/.test(val)), 'Cannot be zero');
+export const SpanIdSchema = z
+    .string()
+    .length(OTLP_SPAN_ID_LENGTH, `Span ID must be ${OTLP_SPAN_ID_LENGTH} characters`)
+    .regex(/^[0-9a-f]+$/, 'Span ID must be lowercase hexadecimal')
+    .refine((val) => !(/^0+$/.test(val)), 'Cannot be zero');
+/**
+ * gen_ai.request.model / gen_ai.response.model identifier.
+ * Covers observed vendor naming patterns (RFC: no format constraint defined).
+ * Watch: widen regex if a provider ships IDs with @, whitespace, or non-ASCII.
+ */
+export const modelIdSchema = z
+    .string()
+    .regex(/^[a-zA-Z0-9._:/-]+$/, 'Invalid model identifier format');
+export const dateRangeSchema = {
+    startDate: z.iso.date().optional().describe('Start (YYYY-MM-DD)'),
+    endDate: z.iso.date().optional().describe('End (YYYY-MM-DD)'),
+};
+/**
+ * Common pagination parameters
+ */
+export const paginationSchema = {
+    limit: z.number().min(1).max(MAX_QUERY_LIMIT).default(DEFAULT_LIMIT).describe('Max results'),
+};
+/**
+ * Pagination with higher default for metrics
+ */
+export const metricsPaginationSchema = {
+    limit: z.number().min(1).max(MAX_QUERY_LIMIT).default(METRICS_DEFAULT_LIMIT).describe('Max results'),
+};
+/**
+ * Backend selection parameter
+ */
+export const backendSchema = {
+    backend: z.enum(['local', 'cloud']).default('cloud').describe('Backend (default: cloud)'),
+};
+/** Maximum length for trace ID */
+export const MAX_TRACE_ID_LENGTH = 64;
+// These are MCP tool input validation bounds (user-supplied query filters),
+// intentionally more conservative than OTel spec limits (128/1024).
+// OTel spec attribute truncation limits live in instrumentation.ts as OTEL_MAX_ATTR_*.
+export const MAX_SPAN_NAME_LENGTH = 512;
+export const MAX_ATTR_KEY_LENGTH = 100;
+export const OTEL_ATTR_PATH_REGEX = /^[a-zA-Z0-9_.]+$/;
+export const OTEL_ATTR_PATH_MSG = 'Attribute path must contain only alphanumeric, dot, or underscore characters';
+export const MAX_ATTR_VALUE_LENGTH = 500;
+export const MAX_ATTR_FILTERS = 20;
+export const MAX_PROVIDER_LENGTH = 100;
+export const MAX_DATASET_LIST_LIMIT = 500;
+export const MAX_DATASET_ID_LENGTH = BITS.B128;
+export const MAX_EXPLANATION_LENGTH = 10240;
+export const SessionIdSchema = z
+    .string()
+    .min(1)
+    .max(MAX_SESSION_ID_LENGTH);
+export const ResponseIdSchema = z
+    .string()
+    .min(1)
+    .max(MAX_SHORT_ID_LENGTH);
+export const AgentIdSchema = z
+    .string()
+    .min(1)
+    .max(MAX_SHORT_ID_LENGTH);
+export const IpAddressSchema = z.union([z.ipv4(), z.ipv6()]);
+export const sessionSchema = {
+    sessionId: SessionIdSchema.optional().describe('Session ID'),
+};
+export const traceIdSchema = {
+    traceId: TraceIdSchema.optional().describe('Trace ID'),
+};
+/** ISO 8601 datetime range (start and end as UTC datetime strings). */
+export const timeRangeSchema = z.object({
+    start: z.iso.datetime(),
+    end: z.iso.datetime(),
+});
+/** Shared correlation ID fields used in evaluation result and webhook payload schemas. */
+export const correlationIdsSchema = {
+    responseId: ResponseIdSchema.optional(),
+    traceId: TraceIdSchema.optional(),
+    sessionId: SessionIdSchema.optional(),
+    agentId: AgentIdSchema.optional(),
+};
+export const commonQuerySchema = {
+    ...backendSchema,
+    ...sessionSchema,
+    ...dateRangeSchema,
+    ...paginationSchema,
+};
+export const exportFilterSchema = {
+    evaluationName: z.string().optional().describe('Evaluation name (substring)'),
+    scoreMin: z.number().optional().describe('Min score threshold'),
+    scoreMax: z.number().optional().describe('Max score threshold'),
+    scoreLabel: z.string().optional().describe('Score label (exact)'),
+    evaluatorType: evaluatorTypeSchema.optional().describe('Evaluator type'),
+    datasetId: z.string().max(MAX_DATASET_ID_LENGTH).optional().describe('Export only evaluations belonging to this dataset'),
+    ...traceIdSchema,
+    ...sessionSchema,
+    ...dateRangeSchema,
+};
+/**
+ * Common export options (limit, batchSize, dryRun)
+ */
+export const exportOptionsSchema = {
+    limit: z.number().min(1).max(MAX_EXPORT_LIMIT).optional().default(MAX_QUERY_LIMIT).describe('Max evaluations to export (max 10000)'),
+    batchSize: z.number().min(1).max(MAX_QUERY_LIMIT).optional().describe('Batch size for export (default 100)'),
+    dryRun: z.boolean().optional().default(false).describe('Preview export without sending'),
+};
+/**
+ * OTel GenAI operation name enum
+ */
+export const operationNameSchema = {
+    operationName: genAIOperationNameSchema.optional().describe('GenAI operation'),
+};
+// ============================================================================
+// Composed Schema Builders
+// ============================================================================
+/**
+ * Build a complete query schema from common parameters.
+ * Use this to create tool input schemas that include standard filtering.
+ *
+ * @example
+ * ```typescript
+ * const myToolSchema = z.object({
+ *   ...queryComposerSchema(),
+ *   customField: z.string(),
+ * });
+ * ```
+ */
+export function queryComposerSchema(overrides) {
+    return {
+        ...(overrides?.backend ?? backendSchema),
+        ...(overrides?.session ?? sessionSchema),
+        ...(overrides?.dateRange ?? dateRangeSchema),
+        ...(overrides?.pagination ?? paginationSchema),
+    };
+}
+/**
+ * Build an export schema from common filter and option parameters.
+ *
+ * @example
+ * ```typescript
+ * const myExportSchema = z.object({
+ *   ...exportComposerSchema(),
+ *   platformSpecificField: z.string(),
+ * });
+ * ```
+ */
+export function exportComposerSchema(overrides) {
+    return {
+        ...(overrides?.filters ?? exportFilterSchema),
+        ...(overrides?.options ?? exportOptionsSchema),
+    };
+}
+//# sourceMappingURL=shared-schemas.js.map

package/dist/lib/core/shared-schemas.js.map

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

package/dist/lib/core/shared-schemas.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.test.d.ts","sourceRoot":"","sources":["../../../src/lib/core/shared-schemas.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/lib/{shared-schemas.test.js → core/shared-schemas.test.js}

@@ -1,23 +1,39 @@
 /**
  * Tests for shared Zod schemas
  */
-import { describe, it } from 'node:test';
+import { describe, it } from 'vitest';
 import assert from 'node:assert';
 import { z } from 'zod';
-import { traceIdSchema, sessionSchema, dateRangeSchema, paginationSchema, backendSchema, } from './shared-schemas.js';
+import { AgentIdSchema, traceIdSchema, TraceIdSchema, sessionSchema, dateRangeSchema, paginationSchema, backendSchema, } from './shared-schemas.js';
+import { MAX_SESSION_ID_LENGTH, MAX_SHORT_ID_LENGTH, OTLP_TRACE_ID_LENGTH } from './constants.js';
+import { DEFAULT_LIMIT } from './input-validator.js';
 describe('shared-schemas', () => {
+    describe('TraceIdSchema', () => {
+        it('should accept valid 32-char lowercase hex', () => {
+            const result = TraceIdSchema.safeParse('a'.repeat(OTLP_TRACE_ID_LENGTH));
+            assert.strictEqual(result.success, true);
+        });
+        it('should reject wrong length', () => {
+            const result = TraceIdSchema.safeParse('abc123');
+            assert.strictEqual(result.success, false);
+        });
+        it('should reject uppercase hex', () => {
+            const result = TraceIdSchema.safeParse('A'.repeat(OTLP_TRACE_ID_LENGTH));
+            assert.strictEqual(result.success, false);
+        });
+        it('should reject non-hex characters', () => {
+            const result = TraceIdSchema.safeParse('g'.repeat(OTLP_TRACE_ID_LENGTH));
+            assert.strictEqual(result.success, false);
+        });
+    });
     describe('traceIdSchema', () => {
         const schema = z.object(traceIdSchema);
         it('should accept valid traceId', () => {
-            const result = schema.safeParse({ traceId: 'abc123' });
+            const result = schema.safeParse({ traceId: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4' });
             assert.strictEqual(result.success, true);
         });
-        it('should accept traceId at max length (64)', () => {
-            const result = schema.safeParse({ traceId: 'a'.repeat(64) });
-            assert.strictEqual(result.success, true);
-        });
-        it('should reject traceId exceeding 64 characters', () => {
-            const result = schema.safeParse({ traceId: 'a'.repeat(65) });
+        it('should reject invalid traceId', () => {
+            const result = schema.safeParse({ traceId: 'too-short' });
             assert.strictEqual(result.success, false);
         });
         it('should accept undefined traceId', () => {
@@ -25,18 +41,32 @@ describe('shared-schemas', () => {
             assert.strictEqual(result.success, true);
         });
     });
+    describe('AgentIdSchema', () => {
+        it('should accept valid agent ID', () => {
+            assert.strictEqual(AgentIdSchema.safeParse('agent-001').success, true);
+        });
+        it('should reject empty string', () => {
+            assert.strictEqual(AgentIdSchema.safeParse('').success, false);
+        });
+        it('should accept at max length', () => {
+            assert.strictEqual(AgentIdSchema.safeParse('a'.repeat(MAX_SHORT_ID_LENGTH)).success, true);
+        });
+        it('should reject exceeding max length', () => {
+            assert.strictEqual(AgentIdSchema.safeParse('a'.repeat(MAX_SHORT_ID_LENGTH + 1)).success, false);
+        });
+    });
     describe('sessionSchema', () => {
         const schema = z.object(sessionSchema);
         it('should accept valid sessionId', () => {
             const result = schema.safeParse({ sessionId: 'session-123' });
             assert.strictEqual(result.success, true);
         });
-        it('should accept sessionId at max length (128)', () => {
-            const result = schema.safeParse({ sessionId: 'a'.repeat(128) });
+        it('should accept sessionId at max length', () => {
+            const result = schema.safeParse({ sessionId: 'a'.repeat(MAX_SESSION_ID_LENGTH) });
             assert.strictEqual(result.success, true);
         });
-        it('should reject sessionId exceeding 128 characters', () => {
-            const result = schema.safeParse({ sessionId: 'a'.repeat(129) });
+        it('should reject sessionId exceeding max characters', () => {
+            const result = schema.safeParse({ sessionId: 'a'.repeat(MAX_SESSION_ID_LENGTH + 1) });
             assert.strictEqual(result.success, false);
         });
         it('should accept undefined sessionId', () => {
@@ -68,7 +98,7 @@ describe('shared-schemas', () => {
             const result = schema.safeParse({});
             assert.strictEqual(result.success, true);
             if (result.success) {
-                assert.strictEqual(result.data.limit, 50);
+                assert.strictEqual(result.data.limit, DEFAULT_LIMIT);
             }
         });
         it('should accept valid limit', () => {
@@ -82,20 +112,20 @@ describe('shared-schemas', () => {
     });
     describe('backendSchema', () => {
         const schema = z.object(backendSchema);
-        it('should default backend to auto', () => {
+        it('should default backend to cloud', () => {
             const result = schema.safeParse({});
             assert.strictEqual(result.success, true);
             if (result.success) {
-                assert.strictEqual(result.data.backend, 'auto');
+                assert.strictEqual(result.data.backend, 'cloud');
             }
         });
         it('should accept local backend', () => {
             const result = schema.safeParse({ backend: 'local' });
             assert.strictEqual(result.success, true);
         });
-        it('should accept signoz backend', () => {
+        it('should reject removed signoz backend', () => {
             const result = schema.safeParse({ backend: 'signoz' });
-            assert.strictEqual(result.success, true);
+            assert.strictEqual(result.success, false);
         });
         it('should reject invalid backend', () => {
             const result = schema.safeParse({ backend: 'invalid' });

package/dist/lib/core/shared-schemas.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.test.js","sourceRoot":"","sources":["../../../src/lib/core/shared-schemas.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/core/units.d.ts

@@ -0,0 +1,67 @@
+export declare const TIME_MS: {
+    readonly MS: 1;
+    readonly SECOND: 1000;
+    readonly MINUTE: 60000;
+    readonly HOUR: 3600000;
+    readonly DAY: 86400000;
+    readonly WEEK: 604800000;
+};
+export declare enum SECONDS {
+    SECOND = 1,
+    MINUTE = 60,
+    HOUR = 3600,
+    DAY = 86400,
+    WEEK = 604800
+}
+export declare const MINUTES_PER_HOUR = 60;
+export declare const HOURS_PER_DAY = 24;
+export declare const DAYS_PER_WEEK = 7;
+export declare const MAX_DAY_OF_MONTH = 31;
+export declare const MONTHS_PER_YEAR = 12;
+export declare const DAYS_PER_YEAR = 365;
+export declare const MIN_VALID_YEAR = 2000;
+export declare const MAX_VALID_YEAR = 2100;
+export declare const NANOSECONDS_PER_SECOND = 1000000000;
+export declare const NANOSECONDS_PER_SECOND_BIGINT = 1000000000n;
+export declare const NANOSECONDS_PER_MILLISECOND_BIGINT = 1000000n;
+export declare const MAX_NANOSECOND_FRACTION: number;
+export declare const COST_DECIMAL_PLACES = 4;
+export declare const ROUND_1DP_FACTOR = 10;
+export declare const PERCENT_MULTIPLIER = 100;
+export declare const ROUND_4DP_FACTOR = 10000;
+export declare const ONE_MILLION = 1000000;
+export declare enum BITS {
+    BIT = 1,
+    B2 = 2,
+    B4 = 4,
+    BYTE = 8,
+    B16 = 16,
+    B32 = 32,
+    B64 = 64,
+    B128 = 128,
+    B256 = 256,
+    B512 = 512
+}
+export declare enum PERCENTILE {
+    P88 = 0.88,
+    P50 = 50,
+    P95 = 95,
+    P99 = 99
+}
+export declare const BYTES: {
+    readonly B: 1;
+    readonly KB: number;
+    readonly MB: number;
+    readonly GB: number;
+    readonly TB: number;
+    readonly PB: number;
+};
+export declare const BYTES_DECIMAL: {
+    readonly B: 1;
+    readonly KB: number;
+    readonly MB: number;
+    readonly GB: number;
+    readonly TB: number;
+    readonly PB: number;
+};
+//# sourceMappingURL=units.d.ts.map

package/dist/lib/core/units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../../src/lib/core/units.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO;;;;;;;CAOV,CAAC;AAEX,oBAAY,OAAO;IAAG,MAAM,IAAI;IAAE,MAAM,KAAK;IAAE,IAAI,OAAQ;IAAE,GAAG,QAAS;IAAE,IAAI,SAAU;CAAE;AAE3F,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,eAAO,MAAM,cAAc,OAAO,CAAC;AACnC,eAAO,MAAM,cAAc,OAAO,CAAC;AAGnC,eAAO,MAAM,sBAAsB,aAAgB,CAAC;AACpD,eAAO,MAAM,6BAA6B,cAAiB,CAAC;AAC5D,eAAO,MAAM,kCAAkC,WAAa,CAAC;AAC7D,eAAO,MAAM,uBAAuB,QAA6B,CAAC;AAElE,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,gBAAgB,QAAS,CAAC;AACvC,eAAO,MAAM,WAAW,UAAM,CAAC;AAI/B,oBAAY,IAAI;IACd,GAAG,IAAI;IAAE,EAAE,IAAI;IAAE,EAAE,IAAI;IAAE,IAAI,IAAI;IAAE,GAAG,KAAK;IAC3C,GAAG,KAAK;IAAE,GAAG,KAAK;IAAE,IAAI,MAAM;IAAE,IAAI,MAAM;IAAE,IAAI,MAAM;CACvD;AAGD,oBAAY,UAAU;IAAG,GAAG,OAAO;IAAE,GAAG,KAAK;IAAE,GAAG,KAAK;IAAE,GAAG,KAAK;CAAE;AAEnE,eAAO,MAAM,KAAK;;;;;;;CAOR,CAAC;AAIX,eAAO,MAAM,aAAa;;;;;;;CAOhB,CAAC"}

package/dist/lib/core/units.js

@@ -0,0 +1,88 @@
+// units.ts
+// ---------- TIME (milliseconds) ----------
+export const TIME_MS = {
+    MS: 1,
+    SECOND: 1_000,
+    MINUTE: 60_000,
+    HOUR: 3_600_000,
+    DAY: 86_400_000,
+    WEEK: 604_800_000,
+};
+// ---------- Time (seconds) ----------
+export var SECONDS;
+(function (SECONDS) {
+    SECONDS[SECONDS["SECOND"] = 1] = "SECOND";
+    SECONDS[SECONDS["MINUTE"] = 60] = "MINUTE";
+    SECONDS[SECONDS["HOUR"] = 3600] = "HOUR";
+    SECONDS[SECONDS["DAY"] = 86400] = "DAY";
+    SECONDS[SECONDS["WEEK"] = 604800] = "WEEK";
+})(SECONDS || (SECONDS = {}));
+// ------- Time (constants) --------------
+export const MINUTES_PER_HOUR = 60;
+export const HOURS_PER_DAY = 24;
+export const DAYS_PER_WEEK = 7;
+export const MAX_DAY_OF_MONTH = 31;
+export const MONTHS_PER_YEAR = 12;
+export const DAYS_PER_YEAR = 365;
+export const MIN_VALID_YEAR = 2000;
+export const MAX_VALID_YEAR = 2100;
+// ---------- Time (nanosecond conversion) ----------
+export const NANOSECONDS_PER_SECOND = 1_000_000_000;
+export const NANOSECONDS_PER_SECOND_BIGINT = 1000000000n;
+export const NANOSECONDS_PER_MILLISECOND_BIGINT = 1000000n; // == BigInt(ONE_MILLION) below
+export const MAX_NANOSECOND_FRACTION = NANOSECONDS_PER_SECOND - 1;
+// ---------- Time (rounding utilities) ----------
+export const COST_DECIMAL_PLACES = 4;
+export const ROUND_1DP_FACTOR = 10;
+export const PERCENT_MULTIPLIER = 100;
+export const ROUND_4DP_FACTOR = 10_000;
+export const ONE_MILLION = 1e6; // == Number(NANOSECONDS_PER_MILLISECOND_BIGINT) above
+// ---------- Bits / Bytes ----------
+const KB = 1 << 10; // 1024 Bits per KB
+export var BITS;
+(function (BITS) {
+    BITS[BITS["BIT"] = 1] = "BIT";
+    BITS[BITS["B2"] = 2] = "B2";
+    BITS[BITS["B4"] = 4] = "B4";
+    BITS[BITS["BYTE"] = 8] = "BYTE";
+    BITS[BITS["B16"] = 16] = "B16";
+    BITS[BITS["B32"] = 32] = "B32";
+    BITS[BITS["B64"] = 64] = "B64";
+    BITS[BITS["B128"] = 128] = "B128";
+    BITS[BITS["B256"] = 256] = "B256";
+    BITS[BITS["B512"] = 512] = "B512";
+})(BITS || (BITS = {}));
+// ---------- Canonical percentile values -----------
+export var PERCENTILE;
+(function (PERCENTILE) {
+    PERCENTILE[PERCENTILE["P88"] = 0.88] = "P88";
+    PERCENTILE[PERCENTILE["P50"] = 50] = "P50";
+    PERCENTILE[PERCENTILE["P95"] = 95] = "P95";
+    PERCENTILE[PERCENTILE["P99"] = 99] = "P99";
+})(PERCENTILE || (PERCENTILE = {}));
+export const BYTES = {
+    B: 1,
+    KB,
+    MB: KB ** BITS.B2, // 1,048,576
+    GB: KB ** (BITS.B2 + BITS.BIT), // 1,073,741,824
+    TB: KB ** BITS.B4, // 1,099,511,627,776
+    PB: KB ** (BITS.B4 + BITS.BIT),
+};
+const DECIMAL_KB = ROUND_1DP_FACTOR * PERCENT_MULTIPLIER; // 1000
+var SI_EXP;
+(function (SI_EXP) {
+    SI_EXP[SI_EXP["KILO"] = 1] = "KILO";
+    SI_EXP[SI_EXP["MEGA"] = 2] = "MEGA";
+    SI_EXP[SI_EXP["GIGA"] = 3] = "GIGA";
+    SI_EXP[SI_EXP["TERA"] = 4] = "TERA";
+    SI_EXP[SI_EXP["PETA"] = 5] = "PETA";
+})(SI_EXP || (SI_EXP = {}));
+export const BYTES_DECIMAL = {
+    B: 1,
+    KB: DECIMAL_KB,
+    MB: DECIMAL_KB ** SI_EXP.MEGA,
+    GB: DECIMAL_KB ** SI_EXP.GIGA,
+    TB: DECIMAL_KB ** SI_EXP.TERA,
+    PB: DECIMAL_KB ** SI_EXP.PETA,
+};
+//# sourceMappingURL=units.js.map

package/dist/lib/core/units.js.map

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