@uploadista/core 0.0.2

package/dist/upload/upload-server.d.ts

@@ -0,0 +1,221 @@
+import { Context, Effect, Layer } from "effect";
+import type { UploadistaError } from "../errors";
+import type { DataStore, DataStoreCapabilities, EventEmitter, InputFile, KvStore, Middleware, UploadEvent, UploadFile, WebSocketConnection } from "../types";
+import { UploadEventEmitter, UploadFileDataStores, UploadFileKVStore } from "../types";
+import { GenerateId, type GenerateIdShape } from "../utils/generate-id";
+/**
+ * Legacy configuration options for UploadServer.
+ *
+ * @deprecated Use Effect Layers instead of this configuration object.
+ * This type is kept for backward compatibility.
+ *
+ * @property dataStore - DataStore instance or factory function
+ * @property kvStore - KV store for upload metadata
+ * @property eventEmitter - Event emitter for upload progress
+ * @property generateId - Optional ID generator (defaults to UUID)
+ * @property middlewares - Optional request middlewares
+ * @property withTracing - Enable Effect tracing for debugging
+ */
+export type UploadServerOptions = {
+    dataStore: ((storageId: string) => Promise<DataStore<UploadFile>>) | DataStore<UploadFile>;
+    kvStore: KvStore<UploadFile>;
+    eventEmitter: EventEmitter<UploadEvent>;
+    generateId?: GenerateIdShape;
+    middlewares?: Middleware[];
+    withTracing?: boolean;
+};
+/**
+ * UploadServer service interface.
+ *
+ * This is the core upload handling service that provides all file upload operations.
+ * It manages upload lifecycle, resumable uploads, progress tracking, and storage integration.
+ *
+ * All operations return Effect types for composable, type-safe error handling.
+ *
+ * @property createUpload - Initiates a new upload and returns metadata
+ * @property uploadChunk - Uploads a chunk of data for an existing upload
+ * @property getCapabilities - Returns storage backend capabilities
+ * @property upload - Complete upload in one operation (create + upload data)
+ * @property uploadFromUrl - Uploads a file from a remote URL
+ * @property getUpload - Retrieves upload metadata by ID
+ * @property read - Reads the complete uploaded file data
+ * @property delete - Deletes an upload and its data
+ * @property subscribeToUploadEvents - Subscribes WebSocket to upload progress events
+ * @property unsubscribeFromUploadEvents - Unsubscribes from upload events
+ *
+ * @example
+ * ```typescript
+ * // Basic upload flow
+ * const program = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *
+ *   // 1. Create upload
+ *   const inputFile: InputFile = {
+ *     storageId: "s3-production",
+ *     size: 1024000,
+ *     type: "image/jpeg",
+ *     fileName: "photo.jpg"
+ *   };
+ *   const upload = yield* server.createUpload(inputFile, "client123");
+ *
+ *   // 2. Upload chunks
+ *   const chunk = new ReadableStream(...);
+ *   const updated = yield* server.uploadChunk(upload.id, "client123", chunk);
+ *
+ *   // 3. Read the uploaded file
+ *   const data = yield* server.read(upload.id, "client123");
+ *
+ *   return upload;
+ * });
+ *
+ * // Upload with WebSocket progress tracking
+ * const uploadWithProgress = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *
+ *   // Subscribe to progress events
+ *   yield* server.subscribeToUploadEvents(uploadId, websocket);
+ *
+ *   // Upload (events will be emitted automatically)
+ *   const result = yield* server.upload(inputFile, clientId, stream);
+ *
+ *   // Unsubscribe when done
+ *   yield* server.unsubscribeFromUploadEvents(uploadId);
+ *
+ *   return result;
+ * });
+ *
+ * // Upload from URL
+ * const urlUpload = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *
+ *   const inputFile: InputFile = {
+ *     storageId: "s3-production",
+ *     size: 0, // Unknown initially
+ *     type: "image/png",
+ *     fileName: "remote-image.png"
+ *   };
+ *
+ *   const upload = yield* server.uploadFromUrl(
+ *     inputFile,
+ *     "client123",
+ *     "https://example.com/image.png"
+ *   );
+ *
+ *   return upload;
+ * });
+ * ```
+ */
+export type UploadServerShape = {
+    createUpload: (inputFile: InputFile, clientId: string | null) => Effect.Effect<UploadFile, UploadistaError>;
+    uploadChunk: (uploadId: string, clientId: string | null, chunk: ReadableStream) => Effect.Effect<UploadFile, UploadistaError>;
+    getCapabilities: (storageId: string, clientId: string | null) => Effect.Effect<DataStoreCapabilities, UploadistaError>;
+    upload: (file: InputFile, clientId: string | null, stream: ReadableStream) => Effect.Effect<UploadFile, UploadistaError>;
+    uploadFromUrl: (inputFile: InputFile, clientId: string | null, url: string) => Effect.Effect<UploadFile, UploadistaError>;
+    getUpload: (uploadId: string) => Effect.Effect<UploadFile, UploadistaError>;
+    read: (uploadId: string, clientId: string | null) => Effect.Effect<Uint8Array, UploadistaError>;
+    delete: (uploadId: string, clientId: string | null) => Effect.Effect<void, UploadistaError>;
+    subscribeToUploadEvents: (uploadId: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError>;
+    unsubscribeFromUploadEvents: (uploadId: string) => Effect.Effect<void, UploadistaError>;
+};
+declare const UploadServer_base: Context.TagClass<UploadServer, "UploadServer", UploadServerShape>;
+/**
+ * Effect-TS context tag for the UploadServer service.
+ *
+ * Use this tag to access the UploadServer in an Effect context.
+ * The server must be provided via a Layer or dependency injection.
+ *
+ * @example
+ * ```typescript
+ * // Access UploadServer in an Effect
+ * const uploadEffect = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *   const upload = yield* server.createUpload(inputFile, clientId);
+ *   return upload;
+ * });
+ *
+ * // Provide UploadServer layer
+ * const program = uploadEffect.pipe(
+ *   Effect.provide(uploadServer),
+ *   Effect.provide(uploadFileKvStore),
+ *   Effect.provide(dataStoreLayer),
+ *   Effect.provide(eventEmitterLayer)
+ * );
+ * ```
+ */
+export declare class UploadServer extends UploadServer_base {
+}
+/**
+ * Creates the UploadServer implementation.
+ *
+ * This function constructs the UploadServer service by composing all required
+ * dependencies (KV store, data stores, event emitter, ID generator). It implements
+ * all upload operations defined in UploadServerShape.
+ *
+ * The server automatically handles:
+ * - Upload lifecycle management (create, resume, complete)
+ * - Progress tracking and event emission
+ * - Storage backend routing based on storageId
+ * - Error handling with proper UploadistaError types
+ *
+ * @returns An Effect that yields the UploadServerShape implementation
+ *
+ * @example
+ * ```typescript
+ * // Create a custom UploadServer layer
+ * const myUploadServer = Layer.effect(
+ *   UploadServer,
+ *   createUploadServer()
+ * );
+ *
+ * // Use in a program
+ * const program = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *   // Use server operations...
+ * }).pipe(Effect.provide(myUploadServer));
+ * ```
+ */
+export declare function createUploadServer(): Effect.Effect<{
+    upload: (inputFile: InputFile, clientId: string | null, stream: ReadableStream) => Effect.Effect<UploadFile, UploadistaError, never>;
+    uploadFromUrl: (inputFile: InputFile, clientId: string | null, url: string) => Effect.Effect<UploadFile, UploadistaError, never>;
+    createUpload: (inputFile: InputFile, clientId: string | null) => Effect.Effect<UploadFile, UploadistaError, never>;
+    uploadChunk: (uploadId: string, clientId: string | null, chunk: ReadableStream) => Effect.Effect<UploadFile, UploadistaError, never>;
+    getUpload: (uploadId: string) => Effect.Effect<UploadFile, UploadistaError, never>;
+    read: (uploadId: string, clientId: string | null) => Effect.Effect<Uint8Array<ArrayBufferLike>, UploadistaError, never>;
+    delete: (uploadId: string, clientId: string | null) => Effect.Effect<void, UploadistaError, never>;
+    getCapabilities: (storageId: string, clientId: string | null) => Effect.Effect<DataStoreCapabilities, UploadistaError, never>;
+    subscribeToUploadEvents: (uploadId: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError, never>;
+    unsubscribeFromUploadEvents: (uploadId: string) => Effect.Effect<void, UploadistaError, never>;
+}, never, UploadFileKVStore | UploadFileDataStores | UploadEventEmitter | GenerateId>;
+/**
+ * Pre-built UploadServer Effect Layer.
+ *
+ * This layer provides a ready-to-use UploadServer implementation that can be
+ * composed with other layers to build a complete upload system.
+ *
+ * Required dependencies:
+ * - UploadFileKVStore: For storing upload metadata
+ * - UploadFileDataStores: For routing to storage backends
+ * - UploadEventEmitter: For progress events
+ * - GenerateId: For creating upload IDs
+ *
+ * @example
+ * ```typescript
+ * // Compose a complete upload system
+ * const fullUploadSystem = Layer.mergeAll(
+ *   uploadServer,
+ *   uploadFileKvStore,
+ *   dataStoreLayer,
+ *   uploadEventEmitter,
+ *   generateIdLayer
+ * );
+ *
+ * // Use in application
+ * const app = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *   // Perform uploads...
+ * }).pipe(Effect.provide(fullUploadSystem));
+ * ```
+ */
+export declare const uploadServer: Layer.Layer<UploadServer, never, UploadFileKVStore | UploadFileDataStores | UploadEventEmitter | GenerateId>;
+export {};
+//# sourceMappingURL=upload-server.d.ts.map

package/dist/upload/upload-server.d.ts.map

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

package/dist/upload/upload-server.js

@@ -0,0 +1,181 @@
+import { Context, Effect, Layer } from "effect";
+import { UploadEventEmitter, UploadFileDataStores, UploadFileKVStore, } from "../types";
+import { GenerateId } from "../utils/generate-id";
+import { createUpload } from "./create-upload";
+import { uploadChunk } from "./upload-chunk";
+import { arrayBuffer, fetchFile } from "./upload-url";
+/**
+ * Effect-TS context tag for the UploadServer service.
+ *
+ * Use this tag to access the UploadServer in an Effect context.
+ * The server must be provided via a Layer or dependency injection.
+ *
+ * @example
+ * ```typescript
+ * // Access UploadServer in an Effect
+ * const uploadEffect = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *   const upload = yield* server.createUpload(inputFile, clientId);
+ *   return upload;
+ * });
+ *
+ * // Provide UploadServer layer
+ * const program = uploadEffect.pipe(
+ *   Effect.provide(uploadServer),
+ *   Effect.provide(uploadFileKvStore),
+ *   Effect.provide(dataStoreLayer),
+ *   Effect.provide(eventEmitterLayer)
+ * );
+ * ```
+ */
+export class UploadServer extends Context.Tag("UploadServer")() {
+}
+/**
+ * Creates the UploadServer implementation.
+ *
+ * This function constructs the UploadServer service by composing all required
+ * dependencies (KV store, data stores, event emitter, ID generator). It implements
+ * all upload operations defined in UploadServerShape.
+ *
+ * The server automatically handles:
+ * - Upload lifecycle management (create, resume, complete)
+ * - Progress tracking and event emission
+ * - Storage backend routing based on storageId
+ * - Error handling with proper UploadistaError types
+ *
+ * @returns An Effect that yields the UploadServerShape implementation
+ *
+ * @example
+ * ```typescript
+ * // Create a custom UploadServer layer
+ * const myUploadServer = Layer.effect(
+ *   UploadServer,
+ *   createUploadServer()
+ * );
+ *
+ * // Use in a program
+ * const program = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *   // Use server operations...
+ * }).pipe(Effect.provide(myUploadServer));
+ * ```
+ */
+export function createUploadServer() {
+    return Effect.gen(function* () {
+        const kvStore = yield* UploadFileKVStore;
+        const eventEmitter = yield* UploadEventEmitter;
+        const generateId = yield* GenerateId;
+        const dataStoreService = yield* UploadFileDataStores;
+        return {
+            upload: (inputFile, clientId, stream) => Effect.gen(function* () {
+                const fileCreated = yield* createUpload(inputFile, clientId, {
+                    dataStoreService,
+                    kvStore,
+                    eventEmitter,
+                    generateId,
+                });
+                return yield* uploadChunk(fileCreated.id, clientId, stream, {
+                    dataStoreService,
+                    kvStore,
+                    eventEmitter,
+                });
+            }),
+            uploadFromUrl: (inputFile, clientId, url) => Effect.gen(function* () {
+                const response = yield* fetchFile(url);
+                const buffer = yield* arrayBuffer(response);
+                // Create a readable stream from the buffer
+                const stream = new ReadableStream({
+                    start(controller) {
+                        controller.enqueue(new Uint8Array(buffer));
+                        controller.close();
+                    },
+                });
+                const fileCreated = yield* createUpload({ ...inputFile, size: buffer.byteLength }, clientId, {
+                    dataStoreService,
+                    kvStore,
+                    eventEmitter,
+                    generateId,
+                });
+                return yield* uploadChunk(fileCreated.id, clientId, stream, {
+                    dataStoreService,
+                    kvStore,
+                    eventEmitter,
+                });
+            }),
+            createUpload: (inputFile, clientId) => Effect.gen(function* () {
+                const fileCreated = yield* createUpload(inputFile, clientId, {
+                    dataStoreService,
+                    kvStore,
+                    eventEmitter,
+                    generateId,
+                });
+                return fileCreated;
+            }),
+            uploadChunk: (uploadId, clientId, chunk) => Effect.gen(function* () {
+                const file = yield* uploadChunk(uploadId, clientId, chunk, {
+                    dataStoreService,
+                    kvStore,
+                    eventEmitter,
+                });
+                return file;
+            }),
+            getUpload: (uploadId) => Effect.gen(function* () {
+                const file = yield* kvStore.get(uploadId);
+                return file;
+            }),
+            read: (uploadId, clientId) => Effect.gen(function* () {
+                const upload = yield* kvStore.get(uploadId);
+                const dataStore = yield* dataStoreService.getDataStore(upload.storage.id, clientId);
+                return yield* dataStore.read(uploadId);
+            }),
+            delete: (uploadId, clientId) => Effect.gen(function* () {
+                const upload = yield* kvStore.get(uploadId);
+                const dataStore = yield* dataStoreService.getDataStore(upload.storage.id, clientId);
+                yield* dataStore.remove(uploadId);
+                yield* kvStore.delete(uploadId);
+                return;
+            }),
+            getCapabilities: (storageId, clientId) => Effect.gen(function* () {
+                const dataStore = yield* dataStoreService.getDataStore(storageId, clientId);
+                return dataStore.getCapabilities();
+            }),
+            subscribeToUploadEvents: (uploadId, connection) => Effect.gen(function* () {
+                yield* eventEmitter.subscribe(uploadId, connection);
+            }),
+            unsubscribeFromUploadEvents: (uploadId) => Effect.gen(function* () {
+                yield* eventEmitter.unsubscribe(uploadId);
+            }),
+        };
+    });
+}
+/**
+ * Pre-built UploadServer Effect Layer.
+ *
+ * This layer provides a ready-to-use UploadServer implementation that can be
+ * composed with other layers to build a complete upload system.
+ *
+ * Required dependencies:
+ * - UploadFileKVStore: For storing upload metadata
+ * - UploadFileDataStores: For routing to storage backends
+ * - UploadEventEmitter: For progress events
+ * - GenerateId: For creating upload IDs
+ *
+ * @example
+ * ```typescript
+ * // Compose a complete upload system
+ * const fullUploadSystem = Layer.mergeAll(
+ *   uploadServer,
+ *   uploadFileKvStore,
+ *   dataStoreLayer,
+ *   uploadEventEmitter,
+ *   generateIdLayer
+ * );
+ *
+ * // Use in application
+ * const app = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *   // Perform uploads...
+ * }).pipe(Effect.provide(fullUploadSystem));
+ * ```
+ */
+export const uploadServer = Layer.effect(UploadServer, createUploadServer());

package/dist/upload/upload-strategy-negotiator.d.ts

@@ -0,0 +1,148 @@
+import type { DataStoreCapabilities, UploadStrategy } from "../types";
+/**
+ * Configuration options for upload strategy negotiation.
+ *
+ * @property fileSize - Size of the file to be uploaded in bytes
+ * @property preferredStrategy - Preferred upload strategy (single, parallel, resumable)
+ * @property preferredChunkSize - Preferred chunk size in bytes
+ * @property parallelUploads - Number of parallel upload connections
+ * @property minChunkSizeForParallel - Minimum file size to consider parallel uploads
+ */
+export type UploadStrategyOptions = {
+    fileSize: number;
+    preferredStrategy?: UploadStrategy;
+    preferredChunkSize?: number;
+    parallelUploads?: number;
+    minChunkSizeForParallel?: number;
+};
+/**
+ * Result of upload strategy negotiation.
+ *
+ * @property strategy - The negotiated upload strategy
+ * @property chunkSize - The negotiated chunk size in bytes
+ * @property parallelUploads - The negotiated number of parallel uploads
+ * @property reasoning - Array of reasoning strings explaining the decisions
+ * @property warnings - Array of warning messages about adjustments made
+ */
+export type NegotiatedStrategy = {
+    strategy: UploadStrategy;
+    chunkSize: number;
+    parallelUploads: number;
+    reasoning: string[];
+    warnings: string[];
+};
+/**
+ * Negotiates the optimal upload strategy based on data store capabilities and file characteristics.
+ *
+ * This class analyzes data store capabilities, file size, and user preferences to determine
+ * the best upload strategy (single, parallel, resumable) and optimal parameters like chunk size
+ * and parallel connection count.
+ *
+ * The negotiator considers:
+ * - Data store capabilities (parallel uploads, resumable uploads, concatenation)
+ * - File size and chunk size constraints
+ * - User preferences and requirements
+ * - Performance optimization opportunities
+ *
+ * @example
+ * ```typescript
+ * // Create negotiator for S3 data store
+ * const negotiator = new UploadStrategyNegotiator(
+ *   s3Capabilities,
+ *   (strategy) => s3Capabilities.supportsStrategy(strategy)
+ * );
+ *
+ * // Negotiate strategy for large file
+ * const result = negotiator.negotiateStrategy({
+ *   fileSize: 100_000_000, // 100MB
+ *   preferredStrategy: "parallel",
+ *   preferredChunkSize: 5_000_000, // 5MB chunks
+ *   parallelUploads: 4
+ * });
+ *
+ * console.log(result.strategy); // "parallel"
+ * console.log(result.chunkSize); // 5_000_000
+ * console.log(result.reasoning); // ["Using preferred strategy: parallel", ...]
+ * ```
+ */
+export declare class UploadStrategyNegotiator {
+    private capabilities;
+    private validateUploadStrategy;
+    /**
+     * Creates a new upload strategy negotiator.
+     *
+     * @param capabilities - Data store capabilities and constraints
+     * @param validateUploadStrategy - Function to validate if a strategy is supported
+     */
+    constructor(capabilities: DataStoreCapabilities, validateUploadStrategy: (strategy: UploadStrategy) => boolean);
+    /**
+     * Negotiates the optimal upload strategy based on options and data store capabilities.
+     *
+     * This method analyzes the provided options and data store capabilities to determine
+     * the best upload strategy, chunk size, and parallel upload settings. It considers
+     * user preferences, file size, and data store constraints to make optimal decisions.
+     *
+     * The negotiation process:
+     * 1. Validates preferred strategy against data store capabilities
+     * 2. Automatically selects strategy based on file size and capabilities
+     * 3. Adjusts chunk size to fit within data store constraints
+     * 4. Validates parallel upload settings
+     * 5. Ensures final strategy is supported by the data store
+     *
+     * @param options - Upload strategy options including file size and preferences
+     * @returns Negotiated strategy with reasoning and warnings
+     *
+     * @example
+     * ```typescript
+     * const result = negotiator.negotiateStrategy({
+     *   fileSize: 50_000_000, // 50MB
+     *   preferredStrategy: "parallel",
+     *   preferredChunkSize: 5_000_000, // 5MB
+     *   parallelUploads: 3
+     * });
+     *
+     * console.log(result.strategy); // "parallel"
+     * console.log(result.chunkSize); // 5_000_000
+     * console.log(result.parallelUploads); // 3
+     * console.log(result.reasoning); // ["Using preferred strategy: parallel", ...]
+     * console.log(result.warnings); // [] (no warnings)
+     * ```
+     */
+    negotiateStrategy(options: UploadStrategyOptions): NegotiatedStrategy;
+    /**
+     * Gets the data store capabilities used by this negotiator.
+     *
+     * @returns The data store capabilities and constraints
+     */
+    getDataStoreCapabilities(): DataStoreCapabilities;
+    /**
+     * Validates upload strategy configuration against data store capabilities.
+     *
+     * This method checks if the provided configuration is valid for the current
+     * data store capabilities without performing the actual negotiation. It's
+     * useful for pre-validation before attempting to negotiate a strategy.
+     *
+     * @param options - Upload strategy options to validate
+     * @returns Validation result with validity flag and error messages
+     *
+     * @example
+     * ```typescript
+     * const validation = negotiator.validateConfiguration({
+     *   fileSize: 10_000_000,
+     *   preferredStrategy: "parallel",
+     *   preferredChunkSize: 1_000_000,
+     *   parallelUploads: 5
+     * });
+     *
+     * if (!validation.valid) {
+     *   console.log("Configuration errors:", validation.errors);
+     *   // Handle validation errors
+     * }
+     * ```
+     */
+    validateConfiguration(options: UploadStrategyOptions): {
+        valid: boolean;
+        errors: string[];
+    };
+}
+//# sourceMappingURL=upload-strategy-negotiator.d.ts.map

package/dist/upload/upload-strategy-negotiator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-strategy-negotiator.d.ts","sourceRoot":"","sources":["../../src/upload/upload-strategy-negotiator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEtE;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,cAAc,CAAC;IACnC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,wBAAwB;IAQjC,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,sBAAsB;IARhC;;;;;OAKG;gBAEO,YAAY,EAAE,qBAAqB,EACnC,sBAAsB,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,OAAO;IAGvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,kBAAkB;IAqHrE;;;;OAIG;IACH,wBAAwB,IAAI,qBAAqB;IAIjD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,GAAG;QACrD,KAAK,EAAE,OAAO,CAAC;QACf,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB;CA8CF"}