ml-cache 1.0.0

package/dist/utils/validator.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * @fileoverview Validation utilities for ml-cache SDK
+ * @module ml-cache/utils/validator
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = void 0;
+exports.validateCredentials = validateCredentials;
+exports.validateS3Config = validateS3Config;
+exports.validateGlacierConfig = validateGlacierConfig;
+exports.validateConfig = validateConfig;
+exports.validateEventType = validateEventType;
+exports.validateEventProperties = validateEventProperties;
+exports.validateEvent = validateEvent;
+exports.isValidTimestamp = isValidTimestamp;
+exports.isValidUUID = isValidUUID;
+const constants_1 = require("../constants");
+/**
+ * Validation error class
+ * @class ValidationError
+ * @extends Error
+ */
+class ValidationError extends Error {
+    /**
+     * Creates a new ValidationError
+     * @param {string} message - Error message
+     * @param {string} [field] - Field that failed validation
+     */
+    constructor(message, field) {
+        super(message);
+        this.name = 'ValidationError';
+        this.code = constants_1.ERROR_CODES.VALIDATION_ERROR;
+        this.field = field;
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Validates AWS credentials
+ * @param {AWSCredentials} credentials - AWS credentials to validate
+ * @throws {ValidationError} If credentials are invalid
+ */
+function validateCredentials(credentials) {
+    if (!credentials) {
+        throw new ValidationError('AWS credentials are required', 'credentials');
+    }
+    if (!credentials.accessKeyId || typeof credentials.accessKeyId !== 'string') {
+        throw new ValidationError('AWS access key ID is required and must be a string', 'credentials.accessKeyId');
+    }
+    if (!credentials.secretAccessKey ||
+        typeof credentials.secretAccessKey !== 'string') {
+        throw new ValidationError('AWS secret access key is required and must be a string', 'credentials.secretAccessKey');
+    }
+    if (credentials.sessionToken !== undefined &&
+        typeof credentials.sessionToken !== 'string') {
+        throw new ValidationError('AWS session token must be a string', 'credentials.sessionToken');
+    }
+}
+/**
+ * Validates S3 configuration
+ * @param {S3Config} config - S3 configuration to validate
+ * @throws {ValidationError} If configuration is invalid
+ */
+function validateS3Config(config) {
+    if (!config) {
+        throw new ValidationError('S3 configuration is required', 's3');
+    }
+    if (!config.bucket || typeof config.bucket !== 'string') {
+        throw new ValidationError('S3 bucket name is required and must be a string', 's3.bucket');
+    }
+    if (!config.region || typeof config.region !== 'string') {
+        throw new ValidationError('S3 region is required and must be a string', 's3.region');
+    }
+    if (config.prefix !== undefined && typeof config.prefix !== 'string') {
+        throw new ValidationError('S3 prefix must be a string', 's3.prefix');
+    }
+}
+/**
+ * Validates Glacier configuration
+ * @param {GlacierConfig} config - Glacier configuration to validate
+ * @throws {ValidationError} If configuration is invalid
+ */
+function validateGlacierConfig(config) {
+    if (!config) {
+        throw new ValidationError('Glacier configuration is required', 'glacier');
+    }
+    if (!config.vaultName || typeof config.vaultName !== 'string') {
+        throw new ValidationError('Glacier vault name is required and must be a string', 'glacier.vaultName');
+    }
+    if (!config.region || typeof config.region !== 'string') {
+        throw new ValidationError('Glacier region is required and must be a string', 'glacier.region');
+    }
+}
+/**
+ * Validates complete SDK configuration
+ * @param {MLCacheConfig} config - SDK configuration to validate
+ * @throws {ValidationError} If configuration is invalid
+ */
+function validateConfig(config) {
+    if (!config) {
+        throw new ValidationError('Configuration is required', 'config');
+    }
+    validateCredentials(config.credentials);
+    if (!config.storageMode) {
+        throw new ValidationError('Storage mode is required', 'storageMode');
+    }
+    const validModes = ['S3', 'GLACIER', 'S3_TO_GLACIER'];
+    if (!validModes.includes(config.storageMode)) {
+        throw new ValidationError(`Invalid storage mode. Must be one of: ${validModes.join(', ')}`, 'storageMode');
+    }
+    if (config.storageMode === 'S3' || config.storageMode === 'S3_TO_GLACIER') {
+        if (!config.s3) {
+            throw new ValidationError('S3 configuration is required for S3 or S3_TO_GLACIER storage mode', 's3');
+        }
+        validateS3Config(config.s3);
+    }
+    if (config.storageMode === 'GLACIER') {
+        if (!config.glacier) {
+            throw new ValidationError('Glacier configuration is required for GLACIER storage mode', 'glacier');
+        }
+        validateGlacierConfig(config.glacier);
+    }
+    if (config.batch) {
+        if (config.batch.maxSize !== undefined) {
+            if (typeof config.batch.maxSize !== 'number' ||
+                config.batch.maxSize < 1) {
+                throw new ValidationError('Batch max size must be a positive number', 'batch.maxSize');
+            }
+        }
+        if (config.batch.maxWaitMs !== undefined) {
+            if (typeof config.batch.maxWaitMs !== 'number' ||
+                config.batch.maxWaitMs < 0) {
+                throw new ValidationError('Batch max wait must be a non-negative number', 'batch.maxWaitMs');
+            }
+        }
+    }
+    if (config.retry) {
+        if (config.retry.maxRetries !== undefined) {
+            if (typeof config.retry.maxRetries !== 'number' ||
+                config.retry.maxRetries < 0) {
+                throw new ValidationError('Max retries must be a non-negative number', 'retry.maxRetries');
+            }
+        }
+    }
+}
+/**
+ * Validates an event type string
+ * @param {string} eventType - Event type to validate
+ * @throws {ValidationError} If event type is invalid
+ */
+function validateEventType(eventType) {
+    if (!eventType || typeof eventType !== 'string') {
+        throw new ValidationError('Event type is required and must be a string', 'eventType');
+    }
+    if (eventType.length > constants_1.MAX_EVENT_TYPE_LENGTH) {
+        throw new ValidationError(`Event type must be at most ${constants_1.MAX_EVENT_TYPE_LENGTH} characters`, 'eventType');
+    }
+    if (!constants_1.EVENT_TYPE_PATTERN.test(eventType)) {
+        throw new ValidationError('Event type must start with a letter and contain only alphanumeric characters and underscores', 'eventType');
+    }
+}
+/**
+ * Validates event properties
+ * @param {Record<string, unknown>} properties - Properties to validate
+ * @throws {ValidationError} If properties are invalid
+ */
+function validateEventProperties(properties) {
+    if (properties === undefined || properties === null) {
+        return;
+    }
+    if (typeof properties !== 'object' || Array.isArray(properties)) {
+        throw new ValidationError('Event properties must be an object', 'properties');
+    }
+    for (const key of Object.keys(properties)) {
+        if (key.length > constants_1.MAX_PROPERTY_KEY_LENGTH) {
+            throw new ValidationError(`Property key "${key}" exceeds maximum length of ${constants_1.MAX_PROPERTY_KEY_LENGTH}`, `properties.${key}`);
+        }
+    }
+}
+/**
+ * Validates a complete event
+ * @param {MLCacheEvent} event - Event to validate
+ * @throws {ValidationError} If event is invalid
+ */
+function validateEvent(event) {
+    if (!event) {
+        throw new ValidationError('Event is required', 'event');
+    }
+    validateEventType(event.eventType);
+    if (event.properties !== undefined) {
+        validateEventProperties(event.properties);
+    }
+    const eventSize = Buffer.byteLength(JSON.stringify(event), 'utf8');
+    if (eventSize > constants_1.MAX_EVENT_SIZE_BYTES) {
+        throw new ValidationError(`Event size (${eventSize} bytes) exceeds maximum allowed size (${constants_1.MAX_EVENT_SIZE_BYTES} bytes)`, 'event');
+    }
+}
+/**
+ * Checks if a value is a valid ISO 8601 timestamp
+ * @param {string} timestamp - Timestamp to validate
+ * @returns {boolean} Whether the timestamp is valid
+ */
+function isValidTimestamp(timestamp) {
+    if (!timestamp || typeof timestamp !== 'string') {
+        return false;
+    }
+    const date = new Date(timestamp);
+    return !isNaN(date.getTime());
+}
+/**
+ * Checks if a value is a valid UUID
+ * @param {string} uuid - UUID to validate
+ * @returns {boolean} Whether the UUID is valid
+ */
+function isValidUUID(uuid) {
+    if (!uuid || typeof uuid !== 'string') {
+        return false;
+    }
+    const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidPattern.test(uuid);
+}
+//# sourceMappingURL=validator.js.map

package/dist/utils/validator.js.map

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "ml-cache",
+  "version": "1.0.0",
+  "description": "SDK to collect and store business/product events for future ML training. Store now, train later when AI becomes affordable.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:esm",
+    "build:esm": "tsc --module ES2020 --outDir dist/esm && mv dist/esm/index.js dist/index.mjs 2>/dev/null || true",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicolasmondain/ml-cache.git"
+  },
+  "keywords": [
+    "ml",
+    "machine-learning",
+    "data-collection",
+    "analytics",
+    "events",
+    "s3",
+    "glacier",
+    "aws",
+    "cold-storage",
+    "future-proof",
+    "ai-training",
+    "data-lake"
+  ],
+  "author": "Nicolas Mondain",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/nicolasmondain/ml-cache/issues"
+  },
+  "homepage": "https://github.com/nicolasmondain/ml-cache#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@aws-sdk/client-glacier": "^3.964.0",
+    "@aws-sdk/client-s3": "^3.964.0"
+  }
+}