digitaltwin-core 0.14.2 → 1.0.0

package/dist/env/env.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Environment variable validation and configuration management
+ *
+ * This utility class provides type-safe environment variable parsing with
+ * validation rules for string, number, boolean, and enum types.
+ */
+/**
+ * Environment variable validation and configuration utility.
+ *
+ * The Env class provides a schema-based approach to validating and parsing
+ * environment variables with type safety and format validation.
+ *
+ * @example
+ * ```typescript
+ * const config = Env.validate({
+ *   PORT: Env.schema.number({ optional: true, default: 3000 }),
+ *   API_URL: Env.schema.string({ format: 'url' }),
+ *   DEBUG: Env.schema.boolean({ optional: true, default: false }),
+ *   NODE_ENV: Env.schema.enum(['development', 'production', 'test'])
+ * });
+ *
+ * // config is now type-safe and validated
+ * console.log(config.PORT); // number
+ * console.log(config.API_URL); // validated URL string
+ * ```
+ */
+export declare class Env {
+    /**
+     * Schema builders for different environment variable types.
+     *
+     * Provides factory methods for creating validation rules for different
+     * data types that can be parsed from environment variables.
+     */
+    static schema: {
+        /**
+         * Creates a string validation rule.
+         *
+         * @param opts - Optional configuration for string validation
+         * @param opts.optional - Whether the environment variable is optional
+         * @param opts.format - Format validation ('url' or 'email')
+         * @returns String validation rule object
+         */
+        string: (opts?: {
+            optional?: boolean;
+            format?: "url" | "email";
+        }) => {
+            optional?: boolean;
+            format?: "url" | "email";
+            type: "string";
+        };
+        /**
+         * Creates a number validation rule.
+         *
+         * @param opts - Optional configuration for number validation
+         * @param opts.optional - Whether the environment variable is optional
+         * @returns Number validation rule object
+         */
+        number: (opts?: {
+            optional?: boolean;
+        }) => {
+            optional?: boolean;
+            type: "number";
+        };
+        /**
+         * Creates a boolean validation rule.
+         *
+         * Accepts 'true'/'false' or '1'/'0' as valid boolean values.
+         *
+         * @param opts - Optional configuration for boolean validation
+         * @param opts.optional - Whether the environment variable is optional
+         * @param opts.default - Default value if the variable is missing
+         * @returns Boolean validation rule object
+         */
+        boolean: (opts?: {
+            optional?: boolean;
+            default?: boolean;
+        }) => {
+            optional?: boolean;
+            default?: boolean;
+            type: "boolean";
+        };
+        /**
+         * Creates an enum validation rule.
+         *
+         * @template T - Array of allowed string values
+         * @param values - Array of allowed values for this environment variable
+         * @returns Enum validation rule object
+         */
+        enum: <T extends string[]>(values: T) => {
+            type: "enum";
+            values: T;
+        };
+    };
+    /**
+     * Stores the last validated configuration.
+     *
+     * This static property holds the most recently validated environment
+     * configuration for reference by other parts of the application.
+     */
+    static config: Record<string, any>;
+    /**
+     * Validates environment variables against a schema definition.
+     *
+     * Parses and validates environment variables according to the provided
+     * schema, returning a type-safe configuration object.
+     *
+     * @template T - The expected type of the returned configuration object
+     * @param schema - Object mapping environment variable names to validation rules
+     * @param rawEnv - Environment variables object (defaults to process.env)
+     * @returns Validated and parsed configuration object
+     *
+     * @throws {Error} When required environment variables are missing
+     * @throws {Error} When environment variables fail format validation
+     *
+     * @example
+     * ```typescript
+     * interface Config {
+     *   DATABASE_URL: string;
+     *   PORT: number;
+     *   DEBUG: boolean;
+     *   NODE_ENV: 'development' | 'production';
+     * }
+     *
+     * const config: Config = Env.validate({
+     *   DATABASE_URL: Env.schema.string({ format: 'url' }),
+     *   PORT: Env.schema.number({ optional: true }),
+     *   DEBUG: Env.schema.boolean({ optional: true, default: false }),
+     *   NODE_ENV: Env.schema.enum(['development', 'production'])
+     * });
+     * ```
+     */
+    static validate<T extends Record<string, any>>(schema: Record<string, any>, rawEnv?: NodeJS.ProcessEnv): T;
+}
+//# sourceMappingURL=env.d.ts.map

package/dist/env/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/env/env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,GAAG;IACZ;;;;;OAKG;IACH,MAAM,CAAC,MAAM;QACT;;;;;;;WAOG;wBACa;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;SAAE;uBAAnC,OAAO;qBAAW,KAAK,GAAG,OAAO;;;QAK9D;;;;;;WAMG;wBACa;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;SAAE;uBAAT,OAAO;;;QAKpC;;;;;;;;;WASG;yBACc;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE;uBAA5B,OAAO;sBAAY,OAAO;;;QAKxD;;;;;;WAMG;eACI,CAAC,SAAS,MAAM,EAAE,UAAU,CAAC;;;;MAIvC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAK;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,oBAAc,GAAG,CAAC;CA2DvG"}

package/dist/env/env.js

@@ -0,0 +1,177 @@
+/**
+ * @fileoverview Environment variable validation and configuration management
+ *
+ * This utility class provides type-safe environment variable parsing with
+ * validation rules for string, number, boolean, and enum types.
+ */
+/**
+ * Environment variable validation and configuration utility.
+ *
+ * The Env class provides a schema-based approach to validating and parsing
+ * environment variables with type safety and format validation.
+ *
+ * @example
+ * ```typescript
+ * const config = Env.validate({
+ *   PORT: Env.schema.number({ optional: true, default: 3000 }),
+ *   API_URL: Env.schema.string({ format: 'url' }),
+ *   DEBUG: Env.schema.boolean({ optional: true, default: false }),
+ *   NODE_ENV: Env.schema.enum(['development', 'production', 'test'])
+ * });
+ *
+ * // config is now type-safe and validated
+ * console.log(config.PORT); // number
+ * console.log(config.API_URL); // validated URL string
+ * ```
+ */
+export class Env {
+    /**
+     * Schema builders for different environment variable types.
+     *
+     * Provides factory methods for creating validation rules for different
+     * data types that can be parsed from environment variables.
+     */
+    static { this.schema = {
+        /**
+         * Creates a string validation rule.
+         *
+         * @param opts - Optional configuration for string validation
+         * @param opts.optional - Whether the environment variable is optional
+         * @param opts.format - Format validation ('url' or 'email')
+         * @returns String validation rule object
+         */
+        string: (opts) => ({
+            type: 'string',
+            ...opts
+        }),
+        /**
+         * Creates a number validation rule.
+         *
+         * @param opts - Optional configuration for number validation
+         * @param opts.optional - Whether the environment variable is optional
+         * @returns Number validation rule object
+         */
+        number: (opts) => ({
+            type: 'number',
+            ...opts
+        }),
+        /**
+         * Creates a boolean validation rule.
+         *
+         * Accepts 'true'/'false' or '1'/'0' as valid boolean values.
+         *
+         * @param opts - Optional configuration for boolean validation
+         * @param opts.optional - Whether the environment variable is optional
+         * @param opts.default - Default value if the variable is missing
+         * @returns Boolean validation rule object
+         */
+        boolean: (opts) => ({
+            type: 'boolean',
+            ...opts
+        }),
+        /**
+         * Creates an enum validation rule.
+         *
+         * @template T - Array of allowed string values
+         * @param values - Array of allowed values for this environment variable
+         * @returns Enum validation rule object
+         */
+        enum: (values) => ({
+            type: 'enum',
+            values
+        })
+    }; }
+    /**
+     * Stores the last validated configuration.
+     *
+     * This static property holds the most recently validated environment
+     * configuration for reference by other parts of the application.
+     */
+    static { this.config = {}; }
+    /**
+     * Validates environment variables against a schema definition.
+     *
+     * Parses and validates environment variables according to the provided
+     * schema, returning a type-safe configuration object.
+     *
+     * @template T - The expected type of the returned configuration object
+     * @param schema - Object mapping environment variable names to validation rules
+     * @param rawEnv - Environment variables object (defaults to process.env)
+     * @returns Validated and parsed configuration object
+     *
+     * @throws {Error} When required environment variables are missing
+     * @throws {Error} When environment variables fail format validation
+     *
+     * @example
+     * ```typescript
+     * interface Config {
+     *   DATABASE_URL: string;
+     *   PORT: number;
+     *   DEBUG: boolean;
+     *   NODE_ENV: 'development' | 'production';
+     * }
+     *
+     * const config: Config = Env.validate({
+     *   DATABASE_URL: Env.schema.string({ format: 'url' }),
+     *   PORT: Env.schema.number({ optional: true }),
+     *   DEBUG: Env.schema.boolean({ optional: true, default: false }),
+     *   NODE_ENV: Env.schema.enum(['development', 'production'])
+     * });
+     * ```
+     */
+    static validate(schema, rawEnv = process.env) {
+        const config = {};
+        for (const [key, rules] of Object.entries(schema)) {
+            const value = rawEnv[key];
+            if (value === undefined || value === '') {
+                if (rules.optional) {
+                    // Use default value if provided
+                    if (rules.default !== undefined) {
+                        config[key] = rules.default;
+                    }
+                    continue;
+                }
+                throw new Error(`Missing environment variable: ${key}`);
+            }
+            switch (rules.type) {
+                case 'string':
+                    if (rules.format === 'url' && !/^https?:\/\/.+$/.test(value)) {
+                        throw new Error(`Invalid URL format for ${key}`);
+                    }
+                    if (rules.format === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+                        throw new Error(`Invalid email format for ${key}`);
+                    }
+                    config[key] = value;
+                    break;
+                case 'number':
+                    const parsed = Number(value);
+                    if (isNaN(parsed)) {
+                        throw new Error(`Invalid number format for ${key}`);
+                    }
+                    config[key] = parsed;
+                    break;
+                case 'boolean':
+                    const lowerValue = value.toLowerCase();
+                    if (lowerValue === 'true' || lowerValue === '1') {
+                        config[key] = true;
+                    }
+                    else if (lowerValue === 'false' || lowerValue === '0') {
+                        config[key] = false;
+                    }
+                    else {
+                        throw new Error(`Invalid boolean format for ${key}, expected true/false or 1/0`);
+                    }
+                    break;
+                case 'enum':
+                    if (!rules.values.includes(value)) {
+                        throw new Error(`Invalid value for ${key}, expected one of ${rules.values.join(', ')}`);
+                    }
+                    config[key] = value;
+                    break;
+            }
+        }
+        this.config = config;
+        return config;
+    }
+}
+//# sourceMappingURL=env.js.map

package/dist/env/env.js.map

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

package/dist/errors/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Custom error classes for Digital Twin framework
+ * Provides structured error handling with codes, status codes, and context
+ */
+/**
+ * Base error class for all Digital Twin errors
+ */
+export declare abstract class DigitalTwinError extends Error {
+    abstract readonly code: string;
+    abstract readonly statusCode: number;
+    readonly timestamp: Date;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, context?: Record<string, unknown>);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Validation error - invalid input data (422 Unprocessable Entity)
+ */
+export declare class ValidationError extends DigitalTwinError {
+    readonly code: "VALIDATION_ERROR";
+    readonly statusCode: 422;
+}
+/**
+ * Resource not found (404)
+ */
+export declare class NotFoundError extends DigitalTwinError {
+    readonly code: "NOT_FOUND";
+    readonly statusCode: 404;
+}
+/**
+ * Authentication required or invalid credentials (401)
+ */
+export declare class AuthenticationError extends DigitalTwinError {
+    readonly code: "AUTHENTICATION_ERROR";
+    readonly statusCode: 401;
+}
+/**
+ * Insufficient permissions (403)
+ */
+export declare class AuthorizationError extends DigitalTwinError {
+    readonly code: "AUTHORIZATION_ERROR";
+    readonly statusCode: 403;
+}
+/**
+ * Storage operation failed (500)
+ */
+export declare class StorageError extends DigitalTwinError {
+    readonly code: "STORAGE_ERROR";
+    readonly statusCode: 500;
+}
+/**
+ * Database operation failed (500)
+ */
+export declare class DatabaseError extends DigitalTwinError {
+    readonly code: "DATABASE_ERROR";
+    readonly statusCode: 500;
+}
+/**
+ * External service (API) error (502)
+ */
+export declare class ExternalServiceError extends DigitalTwinError {
+    readonly code: "EXTERNAL_SERVICE_ERROR";
+    readonly statusCode: 502;
+}
+/**
+ * Configuration error (500)
+ */
+export declare class ConfigurationError extends DigitalTwinError {
+    readonly code: "CONFIGURATION_ERROR";
+    readonly statusCode: 500;
+}
+/**
+ * Queue/Job processing error (500)
+ */
+export declare class QueueError extends DigitalTwinError {
+    readonly code: "QUEUE_ERROR";
+    readonly statusCode: 500;
+}
+/**
+ * File operation error (500)
+ */
+export declare class FileOperationError extends DigitalTwinError {
+    readonly code: "FILE_OPERATION_ERROR";
+    readonly statusCode: 500;
+}
+/**
+ * Type guard to check if an error is a DigitalTwinError
+ */
+export declare function isDigitalTwinError(error: unknown): error is DigitalTwinError;
+/**
+ * Wraps an unknown error into a DigitalTwinError
+ */
+export declare function wrapError(error: unknown, ErrorClass?: typeof DigitalTwinError): DigitalTwinError;
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,8BAAsB,gBAAiB,SAAQ,KAAK;IAChD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAa;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAE9B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAU9D,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAWpC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,gBAAgB;IACjD,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAS;IAC3C,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,gBAAgB;IAC/C,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAS;IACpC,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,gBAAgB;IACrD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAS;IAC/C,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,gBAAgB;IACpD,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAS;IAC9C,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,gBAAgB;IAC9C,QAAQ,CAAC,IAAI,EAAG,eAAe,CAAS;IACxC,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,gBAAgB;IAC/C,QAAQ,CAAC,IAAI,EAAG,gBAAgB,CAAS;IACzC,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,gBAAgB;IACtD,QAAQ,CAAC,IAAI,EAAG,wBAAwB,CAAS;IACjD,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,gBAAgB;IACpD,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAS;IAC9C,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,gBAAgB;IAC5C,QAAQ,CAAC,IAAI,EAAG,aAAa,CAAS;IACtC,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,gBAAgB;IACpD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAS;IAC/C,QAAQ,CAAC,UAAU,EAAG,GAAG,CAAS;CACrC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,GAAE,OAAO,gBAA+B,GAAG,gBAAgB,CAU9G"}

package/dist/errors/index.js

@@ -0,0 +1,149 @@
+/**
+ * Custom error classes for Digital Twin framework
+ * Provides structured error handling with codes, status codes, and context
+ */
+/**
+ * Base error class for all Digital Twin errors
+ */
+export class DigitalTwinError extends Error {
+    constructor(message, context) {
+        super(message);
+        this.timestamp = new Date();
+        this.name = this.constructor.name;
+        this.context = context;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    toJSON() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+                timestamp: this.timestamp.toISOString(),
+                ...(this.context && { context: this.context }),
+                ...(process.env.NODE_ENV !== 'production' && { stack: this.stack })
+            }
+        };
+    }
+}
+/**
+ * Validation error - invalid input data (422 Unprocessable Entity)
+ */
+export class ValidationError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'VALIDATION_ERROR';
+        this.statusCode = 422;
+    }
+}
+/**
+ * Resource not found (404)
+ */
+export class NotFoundError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'NOT_FOUND';
+        this.statusCode = 404;
+    }
+}
+/**
+ * Authentication required or invalid credentials (401)
+ */
+export class AuthenticationError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'AUTHENTICATION_ERROR';
+        this.statusCode = 401;
+    }
+}
+/**
+ * Insufficient permissions (403)
+ */
+export class AuthorizationError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'AUTHORIZATION_ERROR';
+        this.statusCode = 403;
+    }
+}
+/**
+ * Storage operation failed (500)
+ */
+export class StorageError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'STORAGE_ERROR';
+        this.statusCode = 500;
+    }
+}
+/**
+ * Database operation failed (500)
+ */
+export class DatabaseError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'DATABASE_ERROR';
+        this.statusCode = 500;
+    }
+}
+/**
+ * External service (API) error (502)
+ */
+export class ExternalServiceError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'EXTERNAL_SERVICE_ERROR';
+        this.statusCode = 502;
+    }
+}
+/**
+ * Configuration error (500)
+ */
+export class ConfigurationError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'CONFIGURATION_ERROR';
+        this.statusCode = 500;
+    }
+}
+/**
+ * Queue/Job processing error (500)
+ */
+export class QueueError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'QUEUE_ERROR';
+        this.statusCode = 500;
+    }
+}
+/**
+ * File operation error (500)
+ */
+export class FileOperationError extends DigitalTwinError {
+    constructor() {
+        super(...arguments);
+        this.code = 'FILE_OPERATION_ERROR';
+        this.statusCode = 500;
+    }
+}
+/**
+ * Type guard to check if an error is a DigitalTwinError
+ */
+export function isDigitalTwinError(error) {
+    return error instanceof DigitalTwinError;
+}
+/**
+ * Wraps an unknown error into a DigitalTwinError
+ */
+export function wrapError(error, ErrorClass = StorageError) {
+    if (error instanceof DigitalTwinError) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const context = error instanceof Error ? { originalError: error.name } : undefined;
+    // @ts-expect-error - ErrorClass is abstract but we're passing concrete classes
+    return new ErrorClass(message, context);
+}
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Main entry point for the digitaltwin-core package
+ *
+ * This module provides the core functionality for building digital twin applications,
+ * including data collection, processing, asset management, and real-time synchronization.
+ *
+ * @version 1.0.0
+ * @author FARI Team
+ *
+ * @example
+ * ```typescript
+ * import { DigitalTwinEngine, Collector, AssetsManager } from 'digitaltwin-core';
+ *
+ * const engine = new DigitalTwinEngine({ ... });
+ * await engine.start();
+ * ```
+ */
+export { DigitalTwinEngine } from './engine/digital_twin_engine.js';
+export { Collector } from './components/collector.js';
+export { Harvester } from './components/harvester.js';
+export { Handler } from './components/handler.js';
+export { AssetsManager } from './components/assets_manager.js';
+export { GlobalAssetsHandler } from './components/global_assets_handler.js';
+export { CustomTableManager, type CustomTableRecord, type QueryValidationOptions } from './components/custom_table_manager.js';
+export { TilesetManager } from './components/tileset_manager.js';
+export { type AsyncUploadable, isAsyncUploadable } from './components/async_upload.js';
+export { StorageService } from './storage/storage_service.js';
+export { LocalStorageService } from './storage/adapters/local_storage_service.js';
+export { OvhS3StorageService } from './storage/adapters/ovh_storage_service.js';
+export { StorageServiceFactory } from './storage/storage_factory.js';
+export { DatabaseAdapter } from './database/database_adapter.js';
+export { KnexDatabaseAdapter, PostgreSQLConfig, SQLiteConfig } from './database/adapters/knex_database_adapter.js';
+export * from './components/types.js';
+export * from './components/interfaces.js';
+export * from './types/data_record.js';
+export * from './auth/index.js';
+export * from './errors/index.js';
+export * from './validation/index.js';
+export { Logger, LogLevel } from './utils/logger.js';
+export { safeAsync, tryAsync, safeCleanup, retryAsync } from './utils/safe_async.js';
+export { setupGracefulShutdown, type ShutdownOptions } from './utils/graceful_shutdown.js';
+export { mapToDataRecord } from './utils/map_to_data_record.js';
+export { servableEndpoint } from './utils/servable_endpoint.js';
+export { HttpStatus, jsonResponse, successResponse, errorResponse, badRequestResponse, unauthorizedResponse, forbiddenResponse, notFoundResponse, textResponse, fileResponse, multiStatusResponse } from './utils/http_responses.js';
+export type { HttpStatusCode } from './utils/http_responses.js';
+export { QueueManager } from './engine/queue_manager.js';
+export { errorHandler, asyncHandler, notFoundHandler } from './engine/error_handler.js';
+export { HealthChecker, createDatabaseCheck, createRedisCheck, createStorageCheck, performHealthCheck, livenessCheck, type HealthCheck, type HealthCheckFn, type HealthStatus, type ComponentCounts } from './engine/health.js';
+export { UploadProcessor, type TilesetUploadJobData, type UploadJobData, type UploadStatus } from './engine/upload_processor.js';
+export { initializeComponents } from './engine/initializer.js';
+export * from './engine/events.js';
+export * from './engine/endpoints.js';
+export * from './openapi/index.js';
+export { Env } from './env/env.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA;AAGnE,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAA;AAC3E,OAAO,EACH,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC9B,MAAM,sCAAsC,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAChE,OAAO,EAAE,KAAK,eAAe,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAGtF,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAA;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAA;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AAGpE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAGlH,cAAc,uBAAuB,CAAA;AACrC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA;AAGtC,cAAc,iBAAiB,CAAA;AAG/B,cAAc,mBAAmB,CAAA;AAGjC,cAAc,uBAAuB,CAAA;AAGrC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACpF,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AAC/D,OAAO,EACH,UAAU,EACV,YAAY,EACZ,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACtB,MAAM,2BAA2B,CAAA;AAClC,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAG/D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AACvF,OAAO,EACH,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACvB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,YAAY,EACpB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAC9D,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AAGrC,cAAc,oBAAoB,CAAA;AAElC,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAA"}