@streetjs/storage 1.0.0

package/dist/drivers/minio.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @streetjs/storage — MinIO driver submodule (`@streetjs/storage/minio`).
+ *
+ * MinIO speaks the S3 API against a **self-hosted endpoint**, so this driver is a
+ * thin endpoint specialization of the shared S3-style base
+ * ({@link createS3StyleDriver}). It contributes nothing to the contract mapping —
+ * that lives entirely in `s3-base.ts` — and only differs in how the underlying
+ * {@link S3ClientLike} is obtained and in the stable driver name (`"minio"`).
+ *
+ * ## SDK isolation (Requirements 3.1, 3.3)
+ *
+ * This module imports **no provider SDK** at the top level. There are two ways to
+ * obtain a driver:
+ *
+ * 1. **Inject a structural client.** {@link createMinIODriver} accepts an
+ *    already-built {@link S3ClientLike} and delegates straight to the base with
+ *    `name: "minio"`. The `minio` SDK stays an optional peer concern of the
+ *    consumer and is never touched by this package.
+ *
+ * 2. **Let the driver build its own client.** {@link connectMinIODriver} resolves
+ *    the optional `minio` peer SDK with a **lazy dynamic `import()`** performed
+ *    *inside the function* (never at module top level), constructs a MinIO client
+ *    from the supplied endpoint/credentials, adapts it to {@link S3ClientLike},
+ *    and hands it to the base. If the SDK is absent, it throws
+ *    {@link StorageConfigError} rather than a raw module-resolution error.
+ *
+ * Because the driver lives behind the `./minio` subpath export
+ * (`dist/drivers/minio.js`) and is *not* re-exported from the package index, a
+ * consumer only loads this code — and any SDK it lazily resolves — when they
+ * import `@streetjs/storage/minio`. `package.json` lists `minio` as an optional
+ * peer dependency, never a runtime dependency, keeping `streetjs` the only
+ * runtime dependency.
+ *
+ * _Requirements: 2.1, 2.3, 3.3_
+ */
+import type { StorageDriver } from "../driver.js";
+import { type S3ClientLike, type S3StyleDriverOptions } from "./s3-base.js";
+/**
+ * Options for {@link createMinIODriver}. Extends the shared
+ * {@link S3StyleDriverOptions} (clock, native capabilities) but pins the driver
+ * name to `"minio"` — the name is not caller-configurable for this
+ * specialization.
+ */
+export type MinIODriverOptions = Omit<S3StyleDriverOptions, "name">;
+/**
+ * Create a MinIO-backed {@link StorageDriver} over an **injected** structural
+ * {@link S3ClientLike}.
+ *
+ * This is the primary, SDK-free entry point: the caller supplies a client that
+ * already speaks the {@link S3ClientLike} shape (built from the `minio` SDK, an
+ * S3 SDK pointed at a MinIO endpoint, or a test double), and this function
+ * delegates to the shared base with `name: "minio"`. No provider SDK is imported.
+ *
+ * @throws {StorageConfigError} when no client is injected — use
+ *   {@link connectMinIODriver} to build a client from endpoint options instead.
+ */
+export declare function createMinIODriver(client: S3ClientLike, options?: MinIODriverOptions): StorageDriver;
+/** Connection/endpoint options for building a MinIO client via {@link connectMinIODriver}. */
+export interface MinIOConnectionOptions {
+    /** Bucket the driver operates within (required — MinIO is bucket-scoped). */
+    readonly bucket: string;
+    /** MinIO server hostname, e.g. `"127.0.0.1"` or `"minio.example.com"`. */
+    readonly endPoint: string;
+    /** TCP port of the MinIO server. Defaults to the SDK default when omitted. */
+    readonly port?: number;
+    /** Whether to use TLS. Defaults to `true`. */
+    readonly useSSL?: boolean;
+    /** Access key (username) for the MinIO server. */
+    readonly accessKey: string;
+    /** Secret key (password) for the MinIO server. */
+    readonly secretKey: string;
+    /** Optional region hint (MinIO tolerates any value; defaults to `"us-east-1"`). */
+    readonly region?: string;
+    /** Optional session token for temporary credentials. */
+    readonly sessionToken?: string;
+}
+/**
+ * Build a MinIO-backed {@link StorageDriver}, constructing the underlying client
+ * from `connection` options using the optional `minio` peer SDK.
+ *
+ * The SDK is resolved with a **lazy dynamic `import()`** performed inside this
+ * function, so the peer dependency is only touched when a caller actually asks
+ * the driver to build its own client. The resolved SDK client is adapted to the
+ * structural {@link S3ClientLike} and handed to {@link createMinIODriver}.
+ *
+ * @throws {StorageConfigError} when the `minio` SDK is not installed, or when the
+ *   client cannot be constructed from the supplied options.
+ */
+export declare function connectMinIODriver(connection: MinIOConnectionOptions, options?: MinIODriverOptions): Promise<StorageDriver>;
+//# sourceMappingURL=minio.d.ts.map

package/dist/drivers/minio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minio.d.ts","sourceRoot":"","sources":["../../src/drivers/minio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,YAAY,EAOjB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAKtB;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,kBAAuB,GAC/B,aAAa,CAUf;AAED,8FAA8F;AAC9F,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,sBAAsB,EAClC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,aAAa,CAAC,CAqBxB"}

package/dist/drivers/minio.js

@@ -0,0 +1,276 @@
+/**
+ * @streetjs/storage — MinIO driver submodule (`@streetjs/storage/minio`).
+ *
+ * MinIO speaks the S3 API against a **self-hosted endpoint**, so this driver is a
+ * thin endpoint specialization of the shared S3-style base
+ * ({@link createS3StyleDriver}). It contributes nothing to the contract mapping —
+ * that lives entirely in `s3-base.ts` — and only differs in how the underlying
+ * {@link S3ClientLike} is obtained and in the stable driver name (`"minio"`).
+ *
+ * ## SDK isolation (Requirements 3.1, 3.3)
+ *
+ * This module imports **no provider SDK** at the top level. There are two ways to
+ * obtain a driver:
+ *
+ * 1. **Inject a structural client.** {@link createMinIODriver} accepts an
+ *    already-built {@link S3ClientLike} and delegates straight to the base with
+ *    `name: "minio"`. The `minio` SDK stays an optional peer concern of the
+ *    consumer and is never touched by this package.
+ *
+ * 2. **Let the driver build its own client.** {@link connectMinIODriver} resolves
+ *    the optional `minio` peer SDK with a **lazy dynamic `import()`** performed
+ *    *inside the function* (never at module top level), constructs a MinIO client
+ *    from the supplied endpoint/credentials, adapts it to {@link S3ClientLike},
+ *    and hands it to the base. If the SDK is absent, it throws
+ *    {@link StorageConfigError} rather than a raw module-resolution error.
+ *
+ * Because the driver lives behind the `./minio` subpath export
+ * (`dist/drivers/minio.js`) and is *not* re-exported from the package index, a
+ * consumer only loads this code — and any SDK it lazily resolves — when they
+ * import `@streetjs/storage/minio`. `package.json` lists `minio` as an optional
+ * peer dependency, never a runtime dependency, keeping `streetjs` the only
+ * runtime dependency.
+ *
+ * _Requirements: 2.1, 2.3, 3.3_
+ */
+import { StorageConfigError } from "../errors.js";
+import { createS3StyleDriver, } from "./s3-base.js";
+/** The stable {@link StorageDriver.name} surfaced by every MinIO driver. */
+const MINIO_DRIVER_NAME = "minio";
+/**
+ * Create a MinIO-backed {@link StorageDriver} over an **injected** structural
+ * {@link S3ClientLike}.
+ *
+ * This is the primary, SDK-free entry point: the caller supplies a client that
+ * already speaks the {@link S3ClientLike} shape (built from the `minio` SDK, an
+ * S3 SDK pointed at a MinIO endpoint, or a test double), and this function
+ * delegates to the shared base with `name: "minio"`. No provider SDK is imported.
+ *
+ * @throws {StorageConfigError} when no client is injected — use
+ *   {@link connectMinIODriver} to build a client from endpoint options instead.
+ */
+export function createMinIODriver(client, options = {}) {
+    if (client === undefined || client === null) {
+        throw new StorageConfigError("createMinIODriver requires an injected S3-compatible client. " +
+            "Pass an S3ClientLike, or use connectMinIODriver(options) to build one " +
+            "from a MinIO endpoint using the optional 'minio' peer dependency.", { provider: MINIO_DRIVER_NAME });
+    }
+    return createS3StyleDriver(client, { ...options, name: MINIO_DRIVER_NAME });
+}
+/**
+ * Build a MinIO-backed {@link StorageDriver}, constructing the underlying client
+ * from `connection` options using the optional `minio` peer SDK.
+ *
+ * The SDK is resolved with a **lazy dynamic `import()`** performed inside this
+ * function, so the peer dependency is only touched when a caller actually asks
+ * the driver to build its own client. The resolved SDK client is adapted to the
+ * structural {@link S3ClientLike} and handed to {@link createMinIODriver}.
+ *
+ * @throws {StorageConfigError} when the `minio` SDK is not installed, or when the
+ *   client cannot be constructed from the supplied options.
+ */
+export async function connectMinIODriver(connection, options = {}) {
+    const sdk = await loadMinioSdk();
+    let sdkClient;
+    try {
+        sdkClient = new sdk.Client({
+            endPoint: connection.endPoint,
+            port: connection.port,
+            useSSL: connection.useSSL ?? true,
+            accessKey: connection.accessKey,
+            secretKey: connection.secretKey,
+            region: connection.region,
+            sessionToken: connection.sessionToken,
+        });
+    }
+    catch (cause) {
+        throw new StorageConfigError(`Failed to construct a MinIO client for endpoint "${connection.endPoint}".`, { provider: MINIO_DRIVER_NAME, cause });
+    }
+    const client = adaptMinioClient(sdkClient, connection.bucket);
+    return createMinIODriver(client, options);
+}
+// ── Lazy SDK loading ────────────────────────────────────────────────────────
+/**
+ * Lazily resolve the optional `minio` peer SDK. The module specifier is held in
+ * a variable so the compiler does not statically resolve (and therefore require)
+ * the optional peer at build time; the resolution happens only at call time.
+ *
+ * @throws {StorageConfigError} when the SDK is not installed.
+ */
+async function loadMinioSdk() {
+    const specifier = "minio";
+    try {
+        return (await import(specifier));
+    }
+    catch (cause) {
+        throw new StorageConfigError("The optional 'minio' peer dependency is not installed. Install it " +
+            "(`npm install minio`) to build a MinIO client from endpoint options, " +
+            "or inject your own S3ClientLike via createMinIODriver(client).", { provider: MINIO_DRIVER_NAME, cause });
+    }
+}
+// ── SDK → S3ClientLike adapter ────────────────────────────────────────────────
+/** User-metadata prefix MinIO/S3 uses for caller-supplied metadata keys. */
+const USER_META_PREFIX = "x-amz-meta-";
+/** Content-Type header key recognized by the MinIO SDK `metaData` map. */
+const CONTENT_TYPE_KEY = "Content-Type";
+/**
+ * Adapt a MinIO SDK client into the structural {@link S3ClientLike} the base
+ * driver consumes, scoping every call to `bucket`. Multipart methods are left
+ * unimplemented so the facade simulates multipart over the primitives, keeping
+ * behavior identical across providers (Requirement 2.3).
+ */
+function adaptMinioClient(sdk, bucket) {
+    return {
+        async putObject(input) {
+            const metaData = encodeMetaData(input.contentType, input.metadata);
+            const body = Buffer.from(input.body);
+            const result = await sdk.putObject(bucket, input.key, body, body.byteLength, metaData);
+            return { etag: result.etag };
+        },
+        async getObject(input) {
+            let stat;
+            try {
+                stat = await sdk.statObject(bucket, input.key);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+            let stream;
+            try {
+                stream = await sdk.getObject(bucket, input.key);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+            const body = await collectStream(stream);
+            const decoded = decodeMetaData(stat.metaData);
+            return {
+                body,
+                contentType: decoded.contentType,
+                etag: stat.etag,
+                size: stat.size,
+                lastModified: stat.lastModified?.getTime(),
+                metadata: decoded.userMetadata,
+            };
+        },
+        async deleteObject(input) {
+            try {
+                await sdk.removeObject(bucket, input.key);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return;
+                }
+                throw error;
+            }
+        },
+        async listObjects(input) {
+            const stream = sdk.listObjectsV2(bucket, input.prefix, input.delimiter !== true);
+            const items = [];
+            await new Promise((resolve, reject) => {
+                stream.on("data", (entry) => {
+                    if (typeof entry.name === "string") {
+                        items.push({
+                            key: entry.name,
+                            size: entry.size ?? 0,
+                            updatedAt: entry.lastModified?.getTime() ?? 0,
+                        });
+                    }
+                });
+                stream.on("error", reject);
+                stream.on("end", resolve);
+                stream.on("close", resolve);
+            });
+            const sorted = items.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+            return typeof input.limit === "number" ? sorted.slice(0, input.limit) : sorted;
+        },
+        async headObject(input) {
+            try {
+                const stat = await sdk.statObject(bucket, input.key);
+                const decoded = decodeMetaData(stat.metaData);
+                return {
+                    contentType: decoded.contentType,
+                    etag: stat.etag,
+                    size: stat.size,
+                    lastModified: stat.lastModified?.getTime(),
+                    metadata: decoded.userMetadata,
+                };
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async presignUrl(input) {
+            const expirySeconds = Math.max(1, Math.round(input.expiresInMs / 1000));
+            return sdk.presignedUrl(input.op, bucket, input.key, expirySeconds);
+        },
+    };
+}
+// ── metadata encode/decode helpers ─────────────────────────────────────────────
+/** Encode content type + user metadata into the MinIO SDK `metaData` header map. */
+function encodeMetaData(contentType, metadata) {
+    const map = {};
+    if (contentType !== undefined) {
+        map[CONTENT_TYPE_KEY] = contentType;
+    }
+    if (metadata !== undefined) {
+        for (const [key, value] of Object.entries(metadata)) {
+            map[`${USER_META_PREFIX}${key}`] = value;
+        }
+    }
+    return map;
+}
+/**
+ * Decode a MinIO SDK `metaData` map back into a content type and the caller's
+ * user-metadata map, stripping the `x-amz-meta-` prefix. MinIO lowercases header
+ * keys, so lookups are case-insensitive.
+ */
+function decodeMetaData(metaData) {
+    const userMetadata = {};
+    let contentType;
+    if (metaData !== undefined) {
+        for (const [rawKey, value] of Object.entries(metaData)) {
+            const key = rawKey.toLowerCase();
+            if (key === CONTENT_TYPE_KEY.toLowerCase()) {
+                contentType = value;
+            }
+            else if (key.startsWith(USER_META_PREFIX)) {
+                userMetadata[key.slice(USER_META_PREFIX.length)] = value;
+            }
+        }
+    }
+    return { contentType, userMetadata };
+}
+/** Collect a Node {@link Readable} into a single {@link Uint8Array}. */
+async function collectStream(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return new Uint8Array(Buffer.concat(chunks));
+}
+/**
+ * Detect a MinIO/S3 "object does not exist" error so absence maps to `null`
+ * rather than a thrown error, keeping not-found semantics identical to the base.
+ */
+function isNotFound(error) {
+    if (error === null || typeof error !== "object") {
+        return false;
+    }
+    const code = error.code;
+    const statusCode = error.statusCode;
+    return (code === "NoSuchKey" ||
+        code === "NotFound" ||
+        code === "NoSuchObject" ||
+        statusCode === 404);
+}
+//# sourceMappingURL=minio.js.map

package/dist/drivers/minio.js.map

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

package/dist/drivers/r2.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @streetjs/storage — CloudflareR2Driver (submodule `@streetjs/storage/r2`).
+ *
+ * Cloudflare R2 speaks the S3 API, so this driver is a thin **endpoint/credential
+ * specialization** of the shared S3-style base ({@link createS3StyleDriver} in
+ * `s3-base.ts`). It differs from `s3.ts` only in how the underlying client is
+ * built — R2 uses an account-specific endpoint
+ * (`https://<accountId>.r2.cloudflarestorage.com`) with `region: "auto"` — never
+ * in how the {@link StorageDriver} contract is satisfied.
+ *
+ * ## Two ways to obtain a driver
+ *
+ * - {@link createCloudflareR2Driver} wraps an **already-constructed, injected**
+ *   structural {@link S3ClientLike} and returns a driver synchronously. This is
+ *   the SDK-free path: no provider SDK is touched, so it is fully testable with
+ *   an in-memory fake and needs no `@aws-sdk/*` install.
+ * - {@link connectCloudflareR2Driver} **builds its own client** from R2
+ *   connection config. It resolves the S3-compatible SDK through a **lazy
+ *   dynamic `import()` performed inside the function** (never at module top
+ *   level), so the optional peer dependency is only required when this path is
+ *   actually used. If the SDK is not installed and no client was injected, it
+ *   throws {@link StorageConfigError} (Requirement 1.5).
+ *
+ * ## SDK isolation (Requirements 2.1, 3.3)
+ *
+ * This module imports **no provider SDK at the top level** — only this package's
+ * own base/types/errors. The AWS S3 SDK (which R2 uses) is referenced solely via
+ * a dynamic `import()` with a non-literal specifier inside
+ * {@link connectCloudflareR2Driver}, so `tsc` never requires the SDK to be
+ * present and `streetjs` stays the only runtime dependency. This driver is a
+ * submodule-only export (`./r2` → `dist/drivers/r2.js`); it is intentionally not
+ * re-exported from the package's main `index.ts`.
+ *
+ * _Requirements: 2.1, 2.3, 3.3_
+ */
+import type { Clock } from "streetjs";
+import type { StorageDriver } from "../driver.js";
+import { S3StyleDriver, type S3ClientLike, type S3NativeCapabilities } from "./s3-base.js";
+/**
+ * Options for the R2 driver. Mirrors the S3-style base options but omits `name`
+ * — the R2 driver's name is fixed to `"r2"` so provider identity is stable.
+ */
+export interface CloudflareR2DriverOptions {
+    /** Injected clock for deterministic timestamps in tests. Default `systemClock`. */
+    readonly clock?: Clock;
+    /**
+     * Native capability objects to delegate to. Any capability omitted here (and
+     * not derivable from the client) is left `undefined` so the facade simulates
+     * it over the primitives.
+     */
+    readonly capabilities?: S3NativeCapabilities;
+}
+/**
+ * Connection configuration for {@link connectCloudflareR2Driver}. These are the
+ * R2-specific coordinates used to build the endpoint and sign requests.
+ */
+export interface CloudflareR2Config extends CloudflareR2DriverOptions {
+    /** Cloudflare account id — forms the R2 endpoint host. */
+    readonly accountId: string;
+    /** Target R2 bucket name. */
+    readonly bucket: string;
+    /** R2 access key id (S3-compatible credential). */
+    readonly accessKeyId: string;
+    /** R2 secret access key (S3-compatible credential). */
+    readonly secretAccessKey: string;
+    /**
+     * Override the derived endpoint. Defaults to
+     * `https://<accountId>.r2.cloudflarestorage.com`.
+     */
+    readonly endpoint?: string;
+    /** S3 SDK region. R2 ignores region but the SDK requires one; default `"auto"`. */
+    readonly region?: string;
+}
+/**
+ * The CloudflareR2 {@link StorageDriver}: the shared S3-style base pinned to the
+ * `"r2"` provider name. Construction is identical to the base — supply an
+ * {@link S3ClientLike} — the only difference is the fixed name.
+ */
+export declare class CloudflareR2Driver extends S3StyleDriver {
+    constructor(client: S3ClientLike, options?: CloudflareR2DriverOptions);
+}
+/**
+ * Wrap an injected {@link S3ClientLike} as an R2 driver, delegating to
+ * {@link createS3StyleDriver} with the name `"r2"`. Synchronous and SDK-free:
+ * the caller supplies the client, so no provider SDK is resolved here.
+ */
+export declare function createCloudflareR2Driver(client: S3ClientLike, options?: CloudflareR2DriverOptions): StorageDriver;
+/**
+ * Build an R2 driver that owns its client, resolving the S3-compatible SDK
+ * lazily.
+ *
+ * The SDK is loaded through a dynamic `import()` with a non-literal specifier so
+ * it is never a static/top-level dependency: `tsc` does not require it to be
+ * installed, and it is only resolved when this function runs. When the SDK
+ * cannot be resolved, a {@link StorageConfigError} is thrown (Requirement 1.5) —
+ * callers that cannot install the SDK should use {@link createCloudflareR2Driver}
+ * with their own {@link S3ClientLike} instead.
+ */
+export declare function connectCloudflareR2Driver(config: CloudflareR2Config): Promise<StorageDriver>;
+//# sourceMappingURL=r2.d.ts.map

package/dist/drivers/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../src/drivers/r2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,aAAa,EACb,KAAK,YAAY,EAKjB,KAAK,oBAAoB,EAG1B,MAAM,cAAc,CAAC;AAKtB;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,yBAAyB;IACnE,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACvC,MAAM,EAAE,YAAY,EAAE,OAAO,GAAE,yBAA8B;CAG1E;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CAEf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,aAAa,CAAC,CAuCxB"}