bupkis 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.5.0](https://github.com/boneskull/bupkis/compare/bupkis-v0.4.0...bupkis-v0.5.0) (2025-09-18)
+
+
+### Features
+
+* **assertions:** implement "to have key" and "to have exact key" ([8bb53cc](https://github.com/boneskull/bupkis/commit/8bb53cc6c6457b52f16f9057b1287005bc9a80df))
+* more set/map assertions ([ec9e0f4](https://github.com/boneskull/bupkis/commit/ec9e0f46cd2ec0d0d097b54b3d0d9400fbb79c9d)), closes [#27](https://github.com/boneskull/bupkis/issues/27)
+* **util:** implement `get` and `has` functions (like lodash's) supporting keypaths ([8bb53cc](https://github.com/boneskull/bupkis/commit/8bb53cc6c6457b52f16f9057b1287005bc9a80df))
+
+
+### Bug Fixes
+
+* "to satisfy" now accepts any value for comparison ([ec9e0f4](https://github.com/boneskull/bupkis/commit/ec9e0f46cd2ec0d0d097b54b3d0d9400fbb79c9d))
+* **assertions:** widen allowed subjects for "to have keys" assertion ([8bb53cc](https://github.com/boneskull/bupkis/commit/8bb53cc6c6457b52f16f9057b1287005bc9a80df))
+* many edge cases ([ec9e0f4](https://github.com/boneskull/bupkis/commit/ec9e0f46cd2ec0d0d097b54b3d0d9400fbb79c9d))
+
+## [0.4.0](https://github.com/boneskull/bupkis/compare/bupkis-v0.3.0...bupkis-v0.4.0) (2025-09-15)
+
+
+### Features
+
+* implement embeddable assertions ([3050d1c](https://github.com/boneskull/bupkis/commit/3050d1c0d57048a840449935fd0dfead370b0f11)), closes [#46](https://github.com/boneskull/bupkis/issues/46)
+
+
+### Bug Fixes
+
+* **schema:** rename ClassSchema to ConstructibleSchema ([#47](https://github.com/boneskull/bupkis/issues/47)) ([c497a24](https://github.com/boneskull/bupkis/commit/c497a249ad6428a8a2082aadfd7796c1e7f8b82f))
+
 ## [0.3.0](https://github.com/boneskull/bupkis/compare/bupkis-v0.2.0...bupkis-v0.3.0) (2025-09-14)
 
 

package/README.md

@@ -111,9 +111,32 @@ To formalize the conventions at a high level:
   expect(subject, 'phrase', [parameter?, phrase?, parameter?, ...]);
   ```
 
-- One more convention worth mentioning is _negation_.
+- If an assertion's phrase contains something like "to satisfy" or "satisfying", then the next parameter has special meaning. It is somewhat like Jest's `expect.objectContaining()`, but more powerful (prior art: [unexpected's `to satisfy` assertion](https://unexpected.js.org/assertions/any/to-satisfy/)).
 
-  You can _negate_ just about any phrase by prepending it with `not` and a space. For example:
+  There are three (3) things to know about this parameter:
+  1. It matches objects, but only verifies that the keys provided are present and the values match.
+  2. If the value of any given property in an object is a _regular expression_, the real value will be coerced to a string and tested against the regular expression. This provides easy string matching within nested properties.
+  3. _Any assertion_ (including custom assertions) can be embedded within them via the `expect.it()` function:
+
+  ```ts
+  expect(user, 'to satisfy', {
+    name: expect.it('to be a string'),
+    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, // equivalent to "to match" below
+    age: expect.it('to be greater than', 18),
+    roles: [expect.it('to be a string')], // Each array element must be a string
+    metadata: {
+      lastLogin: expect.it('to match', /^\d{4}-\d{2}-\d{2}$/),
+      preferences: {
+        theme: expect.it('to be one of', ['light', 'dark']),
+        notifications: expect.it('to be a boolean'),
+      },
+    },
+  });
+  ```
+
+  > See [Embeddable Assertions][] for more a thorough explanation.
+
+- You can _negate_ just about any phrase by prepending it with `not`. For example:
 
   ```js
   expect(actual, 'to be', expected);
@@ -224,3 +247,4 @@ Copyright © 2025 Christopher Hiller. Licensed under [BlueOak-1.0.0](https://blu
 [assertion-reference]: https://bupkis.zip/assertions
 [tshy]: https://github.com/isaacs/tshy
 [typedoc]: https://typedoc.org
+[embeddable assertions]: https://bupkis.zip/documents/Basic_Usage#embeddable-assertions

package/dist/commonjs/assertion/assertion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assertion.d.ts","sourceRoot":"","sources":["../../../src/assertion/assertion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAY9B,8BAAsB,eAAe,CACnC,KAAK,SAAS,cAAc,EAC5B,IAAI,SAAS,aAAa,CAAC,KAAK,CAAC,EACjC,KAAK,SAAS,cAAc,CAAC,KAAK,CAAC,CACnC,YAAW,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC;IAKtC,QAAQ,CAAC,KAAK,EAAE,KAAK;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI;IALrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBAGT,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,IAAI;IAMrB;;;;;;OAMG;IAEH;;OAEG;IACI,QAAQ,IAAI,MAAM;IAqDzB,SAAS,CAAC,2BAA2B,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EACnE,IAAI,EAAE,IAAI,GACT,YAAY,CAAC,KAAK,CAAC,GAAG,SAAS;IAQlC;;;;;;;OAOG;IACH,SAAS,CAAC,mBAAmB,CAAC,IAAI,SAAS,WAAW,CAAC,KAAK,CAAC,EAC3D,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,GACd,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC;IA4BhC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,iBAAiB,CACzB,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EACpB,GAAG,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,GAC7B,cAAc;IAIjB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,mBAAmB;CAW5B"}
+{"version":3,"file":"assertion.d.ts","sourceRoot":"","sources":["../../../src/assertion/assertion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAa9B,8BAAsB,eAAe,CACnC,KAAK,SAAS,cAAc,EAC5B,IAAI,SAAS,aAAa,CAAC,KAAK,CAAC,EACjC,KAAK,SAAS,cAAc,CAAC,KAAK,CAAC,CACnC,YAAW,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC;IAKtC,QAAQ,CAAC,KAAK,EAAE,KAAK;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI;IALrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBAGT,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,IAAI;IAMrB;;;;;;OAMG;IAEH;;OAEG;IACI,QAAQ,IAAI,MAAM;IAuFzB,SAAS,CAAC,2BAA2B,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EACnE,IAAI,EAAE,IAAI,GACT,YAAY,CAAC,KAAK,CAAC,GAAG,SAAS;IAQlC;;;;;;;OAOG;IACH,SAAS,CAAC,mBAAmB,CAAC,IAAI,SAAS,WAAW,CAAC,KAAK,CAAC,EAC3D,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,GACd,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC;IA4BhC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,iBAAiB,CACzB,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EACpB,GAAG,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,GAC7B,cAAc;IAIjB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,mBAAmB;CAW5B"}

package/dist/commonjs/assertion/assertion.js

@@ -22,12 +22,13 @@ const error_js_1 = require("../error.js");
 const metadata_js_1 = require("../metadata.js");
 const debug = (0, debug_1.default)('bupkis:assertion');
 /**
- * Modified charmap for {@link slug} to use underscores to replace hyphens (and
- * for hyphens to replace everything else that needs replacing).
+ * Modified charmap for {@link slug} to use underscores to replace hyphens (`-`;
+ * and for hyphens to replace everything else that needs replacing) and `<` with
+ * `_` (to distinguish type args)
  *
  * @see {@link BupkisAssertion.generateUniqueId} for usage
  */
-const SLUG_CHARMAP = { ...slug_1.default.charmap, '-': '_' };
+const SLUG_CHARMAP = { ...slug_1.default.charmap, '-': '_', '<': '_', '>': '' };
 class BupkisAssertion {
     parts;
     slots;
@@ -51,54 +52,82 @@ class BupkisAssertion {
      * @returns String representation
      */
     toString() {
-        const expand = (zodType) => {
+        const expand = (zodType, wrapCurlies = false) => {
             const def = 'def' in zodType ? zodType.def : zodType._zod.def;
-            switch (def.type) {
-                case 'custom': {
-                    const meta = metadata_js_1.BupkisRegistry.get(zodType);
-                    if (meta?.name) {
-                        // our name
-                        return `{${meta.name}}`;
-                    }
-                    else if ('Class' in zodType._zod.bag) {
+            let repr = '';
+            const meta = metadata_js_1.BupkisRegistry.get(zodType);
+            if (meta?.name) {
+                // our name
+                repr = meta.name;
+            }
+            else {
+                switch (def.type) {
+                    case 'custom': {
                         // internal Zod class name. will probably break.
-                        return `{${zodType._zod.bag.Class.name}}`;
+                        try {
+                            repr =
+                                'Class' in zodType._zod.bag
+                                    ? `${zodType._zod.bag.Class.name}`
+                                    : 'custom';
+                        }
+                        catch (err) {
+                            debug(`Warning: Unable to extract custom class name from Zod type(did Zod's API change?): ${err}`);
+                            repr = 'custom';
+                        }
+                        break;
                     }
-                    return '{custom}';
+                    case 'default':
+                        repr = `{${expand(def.innerType)}}`;
+                        break;
+                    case 'enum':
+                        repr = `${Object.keys(def.entries).join(' / ')}`;
+                        break;
+                    case 'intersection':
+                        repr = `${expand(def.left)} & ${expand(def.right)}`;
+                        break;
+                    case 'literal':
+                        repr = def.values
+                            .map((value) => `'${value}'`)
+                            .join(' / ');
+                        break;
+                    case 'map':
+                        repr = `Map<${expand(def.keyType)}, ${expand(def.valueType)}>`;
+                        break;
+                    case 'nonoptional':
+                        repr = `${expand(def.innerType)}!`;
+                        break;
+                    case 'nullable':
+                        repr = `${expand(def.innerType)}? | null`;
+                        break;
+                    case 'optional':
+                        repr = `${expand(def.innerType)}?`;
+                        break;
+                    case 'record':
+                        repr = `Record<${expand(def.keyType)}, ${expand(def.valueType)}>`;
+                        break;
+                    case 'set':
+                        repr = `Set<${expand(def.valueType)}>`;
+                        break;
+                    case 'tuple':
+                        repr = `[${def.items.map((value) => expand(value)).join(', ')}]`;
+                        break;
+                    case 'union':
+                        repr = def.options
+                            .map((value) => expand(value))
+                            .join(' | ');
+                        break;
+                    default:
+                        repr = def.type;
+                        break;
                 }
-                case 'default':
-                    return `{${expand(def.innerType)}}`;
-                case 'enum':
-                    return `${Object.keys(def.entries).join(' / ')}`;
-                case 'intersection':
-                    return `${expand(def.left)} & ${expand(def.right)}`;
-                case 'literal':
-                    return def.values
-                        .map((value) => `'${value}'`)
-                        .join(' / ');
-                case 'map':
-                    return `{Map<${expand(def.keyType)}, ${expand(def.valueType)}>`;
-                case 'nonoptional':
-                    return `${expand(def.innerType)}!`;
-                case 'nullable':
-                    return `${expand(def.innerType)}? | null`;
-                case 'optional':
-                    return `${expand(def.innerType)}?`;
-                case 'record':
-                    return `{Record<${expand(def.keyType)}, ${expand(def.valueType)}>`;
-                case 'set':
-                    return `{Set<${expand(def.valueType)}>`;
-                case 'tuple':
-                    return `[${def.items.map(expand).join(', ')}]`;
-                case 'union':
-                    return def.options
-                        .map(expand)
-                        .join(' | ');
-                default:
-                    return `{${def.type}}`;
             }
+            return wrapCurlies ? `{${repr}}` : repr;
         };
-        return `"${this.slots.map(expand).join(' ')}"`;
+        return `"${this.slots
+            .map((slot) => Object.hasOwn(metadata_js_1.BupkisRegistry.get(slot) ?? {}, constant_js_1.kStringLiteral)
+            ? expand(slot)
+            : expand(slot, true))
+            .join(' ')}"`;
     }
     maybeParseValuesArgMismatch(args) {
         if (this.slots.length !== args.length) {

package/dist/commonjs/assertion/assertion.js.map

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

package/dist/commonjs/assertion/impl/assertion-util.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Utility functions for assertion implementations
+ *
+ * @internal
+ * @packageDocumentation
+ */
+import { z } from 'zod/v4';
+import { type ValueToSchemaOptions } from '../../value-to-schema.js';
+/**
+ * Creates a standardized error object for when a callback or nodeback is not
+ * called.
+ *
+ * @param type - The type of callback ('callback' or 'nodeback')
+ * @returns Error object with consistent structure for sync assertions
+ */
+export declare const createNotCalledError: (type: "callback" | "nodeback") => {
+    actual: string;
+    expected: string;
+    message: string;
+};
+/**
+ * Creates a standardized error object for when a callback or nodeback is not
+ * called in async contexts. Uses consistent field naming for async assertions.
+ *
+ * @param type - The type of callback ('callback' or 'nodeback')
+ * @returns Error object with consistent structure for async assertions
+ */
+export declare const createAsyncNotCalledError: (type: "callback" | "nodeback") => {
+    actual: string;
+    expected: string;
+    message: string;
+};
+/**
+ * Creates error objects for nodeback error state mismatches in sync contexts.
+ * Handles cases where an error is expected but not present, or vice versa.
+ *
+ * @param hasError - Whether the nodeback was called with an error
+ * @param expectError - Whether an error was expected
+ * @param error - The actual error value (if any)
+ * @returns Error object if there's a mismatch, undefined if the state matches
+ *   expectations
+ */
+export declare const createErrorMismatchError: (hasError: boolean, expectError: boolean, error?: unknown) => {
+    actual: string;
+    expected: string;
+    message: string;
+} | undefined;
+/**
+ * Creates error objects for nodeback error state mismatches in async contexts.
+ * Handles cases where an error is expected but not present, or vice versa. Uses
+ * consistent field naming and messaging for async assertions.
+ *
+ * @param hasError - Whether the nodeback was called with an error
+ * @param expectError - Whether an error was expected
+ * @param error - The actual error value (if any)
+ * @returns Error object if there's a mismatch, undefined if the state matches
+ *   expectations
+ */
+export declare const createAsyncErrorMismatchError: (hasError: boolean, expectError: boolean, error?: unknown) => {
+    actual: string;
+    expected: string;
+    message: string;
+} | undefined;
+/**
+ * Creates a standardized error object for exact value comparison failures. Used
+ * when a callback/nodeback is called with a value that doesn't match the
+ * expected value using Object.is() strict equality.
+ *
+ * @param actual - The actual value the callback was called with
+ * @param expected - The expected value
+ * @param callbackType - The type of callback for error messaging
+ * @returns Error object with formatted comparison message
+ */
+export declare const createValueMismatchError: (actual: unknown, expected: unknown, callbackType: "callback" | "nodeback") => {
+    actual: unknown;
+    expected: unknown;
+    message: string;
+};
+/**
+ * Creates a Zod schema for validating error parameters in callback assertions.
+ * Handles string literals, RegExp patterns, and object structures for error
+ * matching.
+ *
+ * @param param - The error parameter to create a schema for
+ * @returns Zod schema that can validate the error against the parameter
+ * @throws TypeError if the parameter type is not supported
+ */
+export declare const createErrorSchema: (param: unknown) => z.ZodType;
+/**
+ * Validates a value against a parameter using valueToSchema with specified
+ * options. Centralizes the common pattern of schema creation and validation
+ * used across many callback assertions.
+ *
+ * @param subject - The value to validate
+ * @param param - The parameter to validate against
+ * @param options - Options to pass to valueToSchema
+ * @returns Undefined if validation succeeds, ZodError if validation fails
+ */
+export declare const validateValue: <T = unknown>(subject: T, param: unknown, options?: ValueToSchemaOptions) => z.ZodError<any> | undefined;
+/**
+ * Traps the invocation of a single-parameter callback function for synchronous
+ * testing. Executes the provided function with a callback and captures whether
+ * it was called, what arguments it received, and any errors thrown during
+ * execution.
+ *
+ * @param fn - The function to execute that should call the provided callback
+ * @returns Object containing invocation details: args, called, error, and value
+ */
+export declare const trapCallbackInvocation: (fn: (...args: unknown[]) => unknown) => {
+    args: unknown[];
+    called: boolean;
+    error: unknown;
+    value: unknown;
+};
+/**
+ * Traps the invocation of a nodeback (error-first callback) function for
+ * synchronous testing. Executes the provided function with a nodeback and
+ * captures whether it was called, what arguments it received, and any errors
+ * thrown during execution.
+ *
+ * @param fn - The function to execute that should call the provided nodeback
+ * @returns Object containing invocation details: args, called, error, and value
+ */
+export declare const trapNodebackInvocation: (fn: (...args: unknown[]) => unknown) => {
+    args: unknown[];
+    called: boolean;
+    error: unknown;
+    value: unknown;
+};
+/**
+ * Traps the invocation of a single-parameter callback function for asynchronous
+ * testing. Returns a Promise that resolves with invocation details once the
+ * callback is called or an error occurs. Uses a Proxy to catch errors during
+ * function execution.
+ *
+ * @param fn - The function to execute that should call the provided callback
+ * @returns Promise resolving to object with invocation details: args, called,
+ *   error, and value
+ */
+export declare const trapAsyncCallbackInvocation: (fn: (...args: unknown[]) => unknown) => Promise<{
+    args: unknown[];
+    called: boolean;
+    error: unknown;
+    value: unknown;
+}>;
+/**
+ * Traps the invocation of a nodeback (error-first callback) function for
+ * asynchronous testing. Returns a Promise that resolves with invocation details
+ * once the nodeback is called or an error occurs. Uses a Proxy to catch errors
+ * during function execution. Always resolves (never rejects) to allow assertion
+ * logic to handle error conditions.
+ *
+ * @param fn - The function to execute that should call the provided nodeback
+ * @returns Promise resolving to object with invocation details: args, called,
+ *   error, and value
+ */
+export declare const trapAsyncNodebackInvocation: (fn: (...args: unknown[]) => unknown) => Promise<{
+    args: unknown[];
+    called: boolean;
+    error: unknown;
+    value: unknown;
+}>;
+/**
+ * Executes & traps a `Promise` rejected from an async function, capturing the
+ * error.
+ *
+ * @param fn The function to execute that may throw an error or return a
+ *   `Promise`
+ * @returns Rejection
+ */
+export declare const trapAsyncFnError: (fn: () => unknown) => Promise<unknown>;
+/**
+ * Awaits & traps a Promise, capturing any rejection error.
+ *
+ * @param promise The `Promise` to trap
+ * @returns Rejection
+ */
+export declare const trapPromiseError: (promise: PromiseLike<unknown>) => Promise<unknown>;
+/**
+ * Executes & traps a synchronous function that may throw, capturing any thrown
+ * error and discarding the result.
+ *
+ * @remarks
+ * Avoids throwing `undefined` for some reason.
+ * @param fn Function to execute
+ * @returns Error
+ */
+export declare const trapError: (fn: () => unknown) => unknown;
+//# sourceMappingURL=assertion-util.d.ts.map

package/dist/commonjs/assertion/impl/assertion-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-util.d.ts","sourceRoot":"","sources":["../../../../src/assertion/impl/assertion-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAG3B,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,0BAA0B,CAAC;AAElC;;;;;;GAMG;AAEH,eAAO,MAAM,oBAAoB,GAAI,MAAM,UAAU,GAAG,UAAU;;;;CAIhE,CAAC;AAEH;;;;;;GAMG;AAEH,eAAO,MAAM,yBAAyB,GAAI,MAAM,UAAU,GAAG,UAAU;;;;CAIrE,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,OAAO,EACjB,aAAa,OAAO,EACpB,QAAQ,OAAO;;;;aAqBhB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,GACxC,UAAU,OAAO,EACjB,aAAa,OAAO,EACpB,QAAQ,OAAO;;;;aAqBhB,CAAC;AACF;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GACnC,QAAQ,OAAO,EACf,UAAU,OAAO,EACjB,cAAc,UAAU,GAAG,UAAU;;;;CAQrC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,CAAC,CAAC,OAqBpD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,GAAG,OAAO,EACvC,SAAS,CAAC,EACV,OAAO,OAAO,EACd,UAAS,oBAAyB,gCAKnC,CAAC;AACF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAAI,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO;;;;;CAqBzE,CAAC;AACF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAAI,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO;;;;;CAoBzE,CAAC;AACF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,GACtC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO;UAG3B,OAAO,EAAE;YACP,OAAO;WACR,OAAO;WACP,OAAO;EAkCjB,CAAC;AACF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GACtC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO;UAG3B,OAAO,EAAE;YACP,OAAO;WACR,OAAO;WACP,OAAO;EAoCjB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAU,IAAI,MAAM,OAAO,qBAMvD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAU,SAAS,WAAW,CAAC,OAAO,CAAC,qBAMnE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GAAI,IAAI,MAAM,OAAO,KAAG,OAS7C,CAAC"}