@grest-ts/testkit 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Grest Games OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,413 @@
+# Testkit
+
+## Overview
+
+The testkit provides comprehensive testing capabilities to the framework, mostly focusing on backend integration & component level testing.
+
+### Main features:
+
+* Runs on top of vitest - all normal vitest features are available!
+* Component & integration testing
+    * Parallel execution of tests.
+    * Test a single or multiple components.
+    * Mock or spy communication between runtimes.
+    * Mock external dependencies (like third party API-s) using @mockable decorator.
+    * Manage databases (clone, seed, etc...).
+* Unit testing
+    * Standard vitest and its capabilities. Nothing too special here.
+
+Overall idea is that you get to run your services as if they were running in production, but get access to where you need - like:
+
+* accessing logs
+* accessing metrics
+* accessing & updating config
+* mock or spy on API calls / external requests / events etc...
+* easy setup for isolated databases.
+
+To fully understand the fun, you have to try it out on how easy and fast testing microservice environments can become.
+Start from a single service and easily scale up to multi service environments with ease.
+This is a capability easy to underestimate when starting a project, but you absolutely love it when things start scaling up!
+
+## Capabilities example
+
+```typescript
+import {GGTest} from "@grest-ts/testkit";
+import {MyRuntime} from "./MyRuntime";
+import {MyApi} from "./MyApi.api";
+
+describe("my test", () => {
+    const t = GGTest.startInline(MyRuntime);
+    const client = MyApi.createTestClient();
+
+    test("selector extensions", async () => {
+        // t.myRuntime.logs - from @grest-ts/logger/testkit
+        const cursor = await t.myRuntime.logs.cursor();
+        await client.doSomething();
+        const logs = await cursor.retrieve();
+
+        // t.myRuntime.config - from @grest-ts/config/testkit
+        await t.myRuntime.config.update(MY_CONFIG_KEY, newValue);
+
+        // t.all() selects all runtimes
+        await t.all().config.update(SHARED_KEY, value);
+    });
+
+    test("schema extensions - mock/spy", async () => {
+        // MyApi.mock.methodName - from @grest-ts/http/testkit
+        await client.getUser({id: 1})
+            .with(MyApi.mock.getUser.andReturn({name: "Alice"}));
+
+        // MyApi.spy.methodName - passthrough with validation
+        await client.createUser({name: "Bob"})
+            .with(MyApi.spy.createUser.toMatchObject({name: "Bob"}));
+    });
+
+    test("log expectations with .with()", async () => {
+        await client.doSomething()
+            .with(t.myRuntime.logs.expect("expected message"));
+    });
+
+    test("waitFor - wait for async side effects", async () => {
+        await client.triggerAsyncProcess()
+            .waitFor(t.myRuntime.logs.expect("process completed"));
+    });
+});
+```
+
+---
+
+## GGTestContext
+
+`GGTestContext` is the recommended way to make API calls in tests. It extends `GGContext` and provides lifecycle hooks, API registration, and context management (e.g. auth headers).
+
+### Basic usage
+
+```typescript
+import {GGTest, GGTestContext} from "@grest-ts/testkit";
+import {MyRuntime} from "../src/main";
+import {UserApi} from "../src/api/UserApi.api";
+import {ChecklistApi} from "../src/api/ChecklistApi.api";
+
+describe("my tests", () => {
+    GGTest.startWorker(MyRuntime);
+
+    const alice = new GGTestContext("Alice")
+        .apis({
+            user: UserApi,
+            checklist: ChecklistApi
+        })
+        .beforeAll(async () => {
+            const result = await alice.user.register({
+                username: "alice", email: "alice@example.com", password: "secret123"
+            });
+            alice.set(AUTH_TOKEN, result.token);
+        });
+
+    test('list items', async () => {
+        await alice.checklist.list().toMatchObject([]);
+    });
+});
+```
+
+### `.apis()`
+
+Registers APIs and returns `this` merged with test clients for all registered items.
+After calling `.apis()`, you can access each API directly as a property.
+
+```typescript
+const admin = new GGTestContext("Admin")
+    .apis({
+        building: BuildingApi,
+        apartment: ApartmentApi,
+        client: ClientApi
+    });
+
+// Now call API methods directly:
+await admin.building.sync({...});
+await admin.apartment.list({...});
+```
+
+### `.callOn()`
+
+Call methods on APIs or services not registered via `.apis()`.
+
+```typescript
+// Call an API you didn't register upfront
+await alice.callOn(UserPublicApi).login({username: "alice", password: "secret123"});
+```
+
+### Lifecycle hooks
+
+```typescript
+const alice = new GGTestContext("Alice")
+    .apis({user: UserApi})
+    .resetAfterEach()                           // Reset context state (headers etc) after each test
+    .beforeAll(async () => { /* once */ })       // Runs once before all tests
+    .beforeEach(async () => { /* each */ })      // Runs before each test
+    .afterEach(async () => { /* each */ })       // Runs after each test
+    .afterAll(async () => { /* cleanup */ });    // Runs once after all tests
+```
+
+### Context state management
+
+`GGTestContext` extends `GGContext`, so you can set/get/delete context values (typically auth headers):
+
+```typescript
+alice.set(AUTH_TOKEN, token);       // Set a context value (sent as header)
+alice.get(AUTH_TOKEN);              // Read a context value
+alice.delete(AUTH_TOKEN);           // Remove a context value
+```
+
+### Extending GGTestContext
+
+For domain-specific helpers, extend `GGTestContext`:
+
+```typescript
+import {GGTestContext} from "@grest-ts/testkit";
+
+export class MyUserContext extends GGTestContext {
+
+    public user: User;
+
+    public async login(data: {username: string, password: string}) {
+        const result = await this.callOn(UserPublicApi).login(data);
+        this.set(AUTH_TOKEN, result.token);
+        this.user = result.user;
+    }
+
+    public async loginAndSetup() {
+        await this.login({username: "admin", password: "admin"});
+    }
+}
+
+// Usage in tests:
+const admin = new MyUserContext("Admin")
+    .apis({checklist: ChecklistApi})
+    .beforeAll(async () => {
+        await admin.loginAndSetup();
+    });
+```
+
+---
+
+## Response assertions
+
+All API calls through `GGTestContext` return a `GGTestAction` - a PromiseLike with chainable assertion methods. Assertions are checked when the action is awaited.
+
+### Data assertions
+
+```typescript
+// Exact match
+await alice.user.get({id}).toEqual({id, username: "alice", email: "alice@example.com"});
+
+// Partial match (like Jest toMatchObject)
+await alice.user.get({id}).toMatchObject({username: "alice"});
+
+// Undefined (for void endpoints)
+await alice.user.delete({id}).toBeUndefined();
+
+// Array length
+await alice.checklist.list().toHaveLength(3);
+
+// Array containment
+await alice.checklist.list()
+    .arrayToContain({title: "Buy groceries"});
+```
+
+### Error assertions
+
+When testing error responses, use `.toBeError()` with an error class. After `.toBeError()`, further `.toMatchObject()` calls check the error data.
+
+```typescript
+import {NOT_AUTHORIZED, VALIDATION_ERROR, NOT_FOUND, FORBIDDEN, EXISTS} from "@grest-ts/schema";
+
+// Authorization errors
+await john.building.sync({...}).toBeError(NOT_AUTHORIZED);
+
+// Validation errors - check individual field errors
+await alice.user.register({username: "ab", password: "", email: "invalid"})
+    .toBeError(VALIDATION_ERROR)
+    .toMatchObject({
+        username: {__issue: {message: "Value must be between 3 and 10 characters"}},
+        email: {__issue: {message: "Invalid email format"}},
+    });
+
+// Not found
+await alice.user.get({id: 999}).toBeError(NOT_FOUND);
+
+// Custom error types
+await alice.user.login({username: "alice", password: "wrong"})
+    .toBeError(InvalidCredentialsError);
+```
+
+### Chaining with interceptors
+
+Assertions chain naturally with `.with()` and `.waitFor()`:
+
+```typescript
+await alice.user.login(loginData)
+    .with(BlockerApi.spy.checkBlock.toMatchObject({username: "alice"}))
+    .toMatchObject({user: {username: "alice"}, token: expect.any(String)});
+```
+
+---
+
+## Database cloning
+
+The testkit provides database cloning for test isolation. Each test suite gets its own database clone, ensuring parallel test execution without conflicts.
+
+### MySQL
+
+```typescript
+import {GGTest} from "@grest-ts/testkit";
+import {MyConfig} from "../src/MyConfig";
+import {mysqlLocal} from "../config/local";
+
+describe("my tests", () => {
+    GGTest.startWorker(MyRuntime);
+
+    // Basic clone with explicit source config
+    GGTest.with(MyConfig.mysql).clone({from: mysqlLocal});
+
+    // With seed files
+    GGTest.with(MyConfig.mysql).clone({
+        from: mysqlLocal,
+        seedFiles: ["./test/seed/admin-users.sql"]
+    });
+
+    // Shared clone across parallel workers (same DB for all workers in this group)
+    GGTest.with(MyConfig.mysql).clone({
+        from: mysqlLocal,
+        group: "shared",
+        seedFiles: ["./test/seed/admin-users.sql"]
+    });
+});
+```
+
+### PostgreSQL
+
+```typescript
+// Same API, just with postgres config
+GGTest.with(MyConfig.postgres).clone({from: postgresLocal});
+GGTest.with(MyConfig.postgres).clone({from: postgresLocal, group: "shared"});
+```
+
+### Shorthand forms
+
+```typescript
+// If GGResource has a default value, no `from` needed:
+GGTest.with(MyConfig.mysql).clone();
+
+// Seed files as string or array:
+GGTest.with(MyConfig.mysql).clone("seed.sql");
+GGTest.with(MyConfig.mysql).clone(["seed1.sql", "seed2.sql"]);
+```
+
+### Clone options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `from` | `{host, user}` | Source database config and credentials. Required when GGResource has no default value. |
+| `seedFiles` | `string[]` | SQL files to run after cloning the schema. |
+| `group` | `string` | Group name for shared DB cloning across workers. Tests with the same group share one clone. |
+
+### How it works
+
+1. The source database schema is cloned into a unique test schema (named `{db}_{runId}_{groupId}`).
+2. If the source database doesn't exist and a `schemaFile` is configured, it is created automatically.
+3. Seed files are executed after cloning.
+4. The cloned schema is automatically cleaned up after tests complete.
+5. When `group` is specified, multiple test suites share the same clone via reference counting.
+
+---
+
+## Mocking & spying on @mockable services
+
+Services decorated with `@mockable` can be mocked or spied on in tests using `mockOf()` and `spyOn()`.
+
+This is different from schema-level mock/spy (like `MyApi.mock.method`) which intercepts HTTP calls between runtimes.
+`mockOf`/`spyOn` intercept calls to internal services within a runtime.
+
+### mockOf() - replace with fake data
+
+```typescript
+import {GGTest, mockOf} from "@grest-ts/testkit";
+
+test('mock external service', async () => {
+    await alice.checklist.add({title: "Visit Times Square", address: "123 Main St"})
+        .with(mockOf(AddressResolverService).resolveAddress
+            .toEqual({address: "123 Main St"})              // Validate input
+            .andReturn({lat: 40.7589, lng: -73.9851})       // Return fake data
+        )
+        .toMatchObject({
+            title: "Visit Times Square",
+            lat: 40.7589,
+            lng: -73.9851
+        });
+});
+```
+
+### spyOn() - call through and validate
+
+```typescript
+import {GGTest, spyOn} from "@grest-ts/testkit";
+
+test('spy on external service', async () => {
+    await alice.checklist.add({title: "Visit Times Square", address: "123 Main St"})
+        .with(spyOn(AddressResolverService).resolveAddress
+            .toEqual({address: "123 Main St"})                      // Validate input
+            .responseToMatchObject({lat: 40.7128, lng: -74.0060})   // Validate real response
+        );
+});
+```
+
+### Mock/spy options
+
+```typescript
+// Mock with expected call count
+.with(mockOf(Service).method
+    .andReturn(result)
+    .times(2))                  // Expect exactly 2 calls
+
+// Mock with delay
+.with(mockOf(Service).method
+    .andReturn(result)
+    .sleep(100))                // Wait 100ms before returning
+
+// Mock returning an error
+.with(mockOf(Service).method
+    .andReturn(new NOT_AUTHORIZED()))
+
+// Spy switching to response validation
+.with(spyOn(Service).method
+    .toMatchObject({input: "data"})     // Validate input
+    .response.toMatchObject({out: 1})   // Switch to response, then validate
+)
+
+// Spy expecting error response
+.with(spyOn(Service).method
+    .toBeError(NOT_FOUND)
+)
+```
+
+### Schema mock/spy vs @mockable mock/spy
+
+| | Schema mock/spy (`MyApi.mock.method`) | @mockable mock/spy (`mockOf(Service).method`) |
+|---|---|---|
+| **What it intercepts** | HTTP calls between runtimes | Internal method calls within a runtime |
+| **Use case** | Mock/spy on service-to-service communication | Mock/spy on external dependencies (3rd party APIs, etc.) |
+| **How to use** | `MyApi.mock.method.andReturn(...)` | `mockOf(Service).method.andReturn(...)` |
+| **Import** | `import "@grest-ts/http/testkit"` | `import {mockOf, spyOn} from "@grest-ts/testkit"` |
+
+---
+
+## Usage
+
+Check README-testkit.md files within packages you are interested in. Common ones being:
+
+- [Logger](../../packages/logger/logger/README-testkit.md) - Accessing logs during the test flow.
+- [Metrics](../../packages/metrics/README-testkit.md) - Accessing metrics during the test flow.
+
+## Extending framework with custom packages and adding testkit capabilities.
+
+- [Extending Guide](./README-extending.md) - How to create testkit extensions - adding capabilities to the testing framework for custom packages.

package/dist/src/GGBundleTest.d.ts

@@ -0,0 +1,8 @@
+interface GGBundleTestOptions {
+    entryPoint: string;
+}
+export declare class GGBundleTest {
+    static verify(options: GGBundleTestOptions): void;
+}
+export {};
+//# sourceMappingURL=GGBundleTest.d.ts.map

package/dist/src/GGBundleTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGBundleTest.d.ts","sourceRoot":"","sources":["../../src/GGBundleTest.ts"],"names":[],"mappings":"AAoBA,UAAU,mBAAmB;IACzB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,YAAY;IAErB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,mBAAmB;CA8D7C"}

package/dist/src/GGBundleTest.js

@@ -0,0 +1,75 @@
+import { describe, test, expect, beforeAll } from "vitest";
+import { fileURLToPath } from "url";
+const FORBIDDEN_SYMBOLS = {
+    IPC: ['IPCServer', 'IPCClient', 'IPCSocket'],
+    'discovery-local': [
+        'GGLocalDiscoveryClient',
+        'GGLocalDiscoveryResilientClient',
+        'GGLocalDiscoveryServer',
+    ],
+    testkit: [
+        'GGTestRunner',
+        'GGTestRuntime',
+        'startWorker',
+        'startInline',
+        'startIsolated',
+    ],
+};
+export class GGBundleTest {
+    static verify(options) {
+        const entryPoint = options.entryPoint.startsWith('file://')
+            ? fileURLToPath(options.entryPoint)
+            : options.entryPoint;
+        describe("production bundle", () => {
+            let result;
+            let bundleText;
+            beforeAll(async () => {
+                const esbuild = await import("esbuild");
+                const externalizeNonGG = {
+                    name: 'externalize-non-gg',
+                    setup(build) {
+                        build.onResolve({ filter: /./ }, args => {
+                            // Only externalize import statements, not entry points
+                            if (args.kind !== 'import-statement' && args.kind !== 'dynamic-import')
+                                return null;
+                            // Keep relative/absolute paths bundled
+                            if (args.path.startsWith('.') || args.path.startsWith('/'))
+                                return null;
+                            // Keep @grest-ts/* packages bundled
+                            if (args.path.startsWith('@grest-ts/'))
+                                return null;
+                            return { path: args.path, external: true };
+                        });
+                    }
+                };
+                result = await esbuild.build({
+                    entryPoints: [entryPoint],
+                    bundle: true,
+                    write: false,
+                    platform: 'node',
+                    format: 'esm',
+                    define: { 'process.env.NODE_ENV': '"production"' },
+                    plugins: [externalizeNonGG],
+                });
+                bundleText = result.outputFiles.map(f => f.text).join('\n');
+            });
+            test("bundle has no errors", () => {
+                expect(result.errors).toHaveLength(0);
+            });
+            test("bundle is non-trivially sized", () => {
+                expect(bundleText.length).toBeGreaterThan(100);
+            });
+            for (const [group, symbols] of Object.entries(FORBIDDEN_SYMBOLS)) {
+                for (const symbol of symbols) {
+                    test(`does not contain dev-only symbol: ${symbol} (${group})`, () => {
+                        // Match actual definitions (var X = class, class X, function X)
+                        // but not dead-code references like: const { X } = await null
+                        const definitionPattern = new RegExp(`\\b(var|let|const|class|function)\\s+${symbol}\\b`);
+                        expect(bundleText).not.toMatch(definitionPattern);
+                    });
+                }
+            }
+        });
+    }
+}
+//# sourceMappingURL=GGBundleTest.js.map

package/dist/src/GGBundleTest.js.map

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

package/dist/src/GGTest.d.ts

@@ -0,0 +1,131 @@
+import { GG_TEST_RESOURCE, TestResource } from "./GGTestRunner";
+import { RuntimeConstructor, RuntimeInput, StartResult, Selector } from "./testers/RuntimeSelector";
+import { IGGTestWith } from "./testers/IGGTestWith";
+/**
+ * Make a result awaitable by adding a then() method.
+ */
+type Awaitable<T> = T & PromiseLike<T>;
+/**
+ * Static API for test setup operations.
+ * Use GGTest.startWorker(), GGTest.with(), etc. in test files.
+ *
+ * @example
+ * // Single runtime
+ * const t = GGTest.startWorker(MainRuntime);
+ * t.logs.cursor();
+ *
+ * // Multiple instances
+ * const t = GGTest.startWorker([MainRuntime, MainRuntime]);
+ * t[0].logs.cursor();
+ *
+ * // Named runtimes
+ * const t = GGTest.startWorker({main: MainRuntime, sub: SubRuntime});
+ * t.main.logs.cursor();
+ * t.sub.config.update();
+ */
+export declare class GGTest {
+    private static readonly forceCoverageInline;
+    /**
+     * Get a resource wrapper for calling test operations.
+     * Returns an object with methods defined by the resource's [GG_TEST_RESOURCE].
+     *
+     * @example
+     * GGTest.with(MyConfig.mysql).clone();
+     * GGTest.with(MyConfig.mysql).clone("seed.sql");
+     */
+    static with<T extends TestResource>(resource: T): T[typeof GG_TEST_RESOURCE];
+    /**
+     * Start runtimes in inline mode.
+     * Inline mode runs the service code in the same process as the test.
+     *
+     * @example
+     * // Single runtime
+     * const t = GGTest.startInline(MainRuntime);
+     *
+     * // Array of runtimes (multiple instances)
+     * const t = GGTest.startInline([MainRuntime, MainRuntime]);
+     *
+     * // Object with named runtimes
+     * const t = GGTest.startInline({main: MainRuntime, sub: SubRuntime});
+     */
+    static startInline<const T extends RuntimeInput>(input: T): Awaitable<StartResult<T>>;
+    /**
+     * Start runtimes in worker mode.
+     * Worker mode runs the service code in a worker thread.
+     *
+     * @example
+     * // Single runtime
+     * const t = GGTest.startWorker(MainRuntime);
+     *
+     * // Array of runtimes (multiple instances)
+     * const t = GGTest.startWorker([MainRuntime, MainRuntime]);
+     *
+     * // Object with named runtimes
+     * const t = GGTest.startWorker({main: MainRuntime, sub: SubRuntime});
+     */
+    static startWorker<T extends RuntimeInput>(input: T): Awaitable<StartResult<T>>;
+    /**
+     * Start runtimes in isolated mode.
+     * Isolated mode runs the service code in a separate process.
+     *
+     * @example
+     * // Single runtime
+     * const t = GGTest.startIsolated(MainRuntime);
+     *
+     * // Array of runtimes (multiple instances)
+     * const t = GGTest.startIsolated([MainRuntime, MainRuntime]);
+     *
+     * // Object with named runtimes
+     * const t = GGTest.startIsolated({main: MainRuntime, sub: SubRuntime});
+     */
+    static startIsolated<T extends RuntimeInput>(input: T): Awaitable<StartResult<T>>;
+    /**
+     * Wait for an async expectation to be satisfied.
+     * Use this for standalone async expectations outside of action chains.
+     *
+     * Polls the expectation every 20ms until it's satisfied or timeout is reached.
+     *
+     * @param expectation - The expectation to wait for
+     * @param timeout - Max time to wait in ms (default: 5000)
+     *
+     * @example
+     * // Wait for a log after injecting an event
+     * await UserEventsPublisher.inject.registered({...});
+     * await GGTest.waitFor(t.logs.expect(/validation failed/i));
+     *
+     * @example
+     * // Wait for a metric to be incremented
+     * await GGTest.waitFor(t.main.metrics.expect(SomeMetric).inc({label: 'value'}));
+     */
+    static waitFor(expectation: IGGTestWith, timeout?: number): Promise<void>;
+    private static startWithMode;
+    /**
+     * Extract runtime constructors from the input in the order they should be created.
+     */
+    private static extractConstructors;
+    /**
+     * Start runtimes immediately (for in-test usage).
+     * Runtimes are automatically tracked by the runner for afterEach cleanup.
+     */
+    private static startRuntimesInTestBlock;
+    /**
+     * Makes a result thenable by adding a then() method.
+     * This allows both sync and async usage patterns.
+     *
+     * IMPORTANT: The then() method removes itself after being called to prevent
+     * infinite thenable resolution. When onfulfilled returns the result,
+     * JavaScript would try to resolve it again if then() still existed.
+     */
+    private static makeAwaitable;
+    private static getCoverageMode;
+    private static createRuntimes;
+}
+/**
+ * @deprecated Use StartResult instead
+ */
+export type { RuntimeResult } from "./testers/RuntimeSelector";
+/**
+ * @deprecated Use Awaitable<StartResult<T>> instead
+ */
+export type AwaitableRuntimeResult<R extends RuntimeConstructor[]> = Awaitable<Selector<R>>;
+//# sourceMappingURL=GGTest.d.ts.map

package/dist/src/GGTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGTest.d.ts","sourceRoot":"","sources":["../../src/GGTest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,gBAAgB,EAAgC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAC,kBAAkB,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAC,MAAM,2BAA2B,CAAC;AAGlG,OAAO,EAAC,WAAW,EAAC,MAAM,uBAAuB,CAAC;AAMlD;;GAEG;AACH,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAM;IAQf,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAwC;IAMnF;;;;;;;OAOG;WACW,IAAI,CAAC,CAAC,SAAS,YAAY,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,gBAAgB,CAAC;IAInF;;;;;;;;;;;;;OAaG;WACW,WAAW,CAAC,KAAK,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI5F;;;;;;;;;;;;;OAaG;WACW,WAAW,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAItF;;;;;;;;;;;;;OAaG;WACW,aAAa,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAIxF;;;;;;;;;;;;;;;;;OAiBG;WACiB,OAAO,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA4C5F,OAAO,CAAC,MAAM,CAAC,aAAa;IAqB5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAuBlC;;;OAGG;mBACkB,wBAAwB;IAM7C;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAkB5B,OAAO,CAAC,MAAM,CAAC,eAAe;IAO9B,OAAO,CAAC,MAAM,CAAC,cAAc;CAsChC;AAMD;;GAEG;AACH,YAAY,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,kBAAkB,EAAE,IAAI,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC"}