gruber 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -7,6 +7,36 @@ layout: simple.njk
 
 This file documents notable changes to the project
 
+## next
+
+**fixes**
+
+- `Terminator#waitForSignals` no longer exits the process
+
+**unstable**
+
+- Add `Structure.record`
+
+## 0.9.1
+
+**features**
+
+- Add `Structure.nullable`
+- Add `Structure.enum`
+- Add `Structure.undefined`
+- Add `Structure.optional`
+- Add `pickProperties` utility
+- Add `getOrInsert` utility
+
+**improved**
+
+- short-circuit optional-parameters during TypeScript URL param parsing
+
+**unstable**
+
+- Add `Structure.fromJSONSchema`
+- Add `Structure.tuple`
+
 ## 0.9
 
 **features**

package/config/structure.d.ts

@@ -130,6 +130,72 @@ export declare class Structure<T> {
      * ```
      */
     static union<T extends Structure<unknown>[]>(types: T): Structure<Infer<T[number]>>;
+    /**
+     * @unstable
+     *
+     * Attempts to create a Structure from a parsed [JSON Schema](https://json-schema.org/specification) value.
+     * This is implemented on a as-needed bases, currently it supports:
+     * - "const" → `Structure.literal`
+     * - type=string → `Structure.string`
+     * - type=number → `Structure.number`
+     * - type=boolean → `Structure.boolean`
+     * - type=array → "items" are recursively parsed and put into a `Structure.array`
+     * - type=object → "properties" are recursively parsed and put into a `Structure.object`
+     * - anyOf → `Structure.union`
+     *
+     * ```js
+     * Structure.fromJSONSchema({ type: "string" })
+     * Structure.fromJSONSchema({ type: "number" })
+     * Structure.fromJSONSchema({ type: "boolean" })
+     * Structure.fromJSONSchema({
+     *   type: "object",
+     *   properties: {
+     *     name: { type:"string" },
+     *     age: { type: "number" }
+     *   },
+     *   required: ["name"]
+     * })
+     * Structure.fromJSONSchema({ type: "array", items: { type: "string" } })
+     * Structure.fromJSONSchema({
+     *   anyOf: [
+     *     { type: "string" },
+     *     { type: "number" }
+     *   ]
+     * });
+     * ```
+     *
+     * notes
+     * - array "prefixItems" are not supported, maybe they could be mapped to tuples?
+     */
+    static fromJSONSchema(schema: any): Structure<any>;
+    /**
+     * @unstable
+     *
+     * Creates a Structure for arrays where each index has a different validation
+     *
+     * ```js
+     * Structure.tuple([Structure.string(), Structure.number()])
+     * ```
+     */
+    static tuple<const T extends Structure<any>[]>(types: T): Structure<InferObject<T>>;
+    /**
+     * @unstable
+     *
+     * Creates a Structure for objects that map a key to a common type of value
+     *
+     * ```js
+     * Structure.record(Structure.string(), Structure.number())
+     * Structure.record(
+     *   Structure.string(),
+     *   Structure.object({ name: Structure.string() })
+     * )
+     * Structure.record(
+     *   Structure.enum(["name", "address", "emailAddress"]),
+     *   Structure.string()
+     * )
+     * ```
+     */
+    static record<K extends string, V>(keyStruct: Structure<K>, valueStruct: Structure<V>): Structure<Record<K, V>>;
     /**
      * Define a Structure to validate the value is `null`
      *
@@ -171,5 +237,37 @@ export declare class Structure<T> {
      * ```
      */
     static date(): Structure<Date>;
+    /**
+     * Creates a Structure that validates a value is either another structure or a null value
+     *
+     * ```js
+     * Structure.nullable(Structure.string())
+     * ```
+     */
+    static nullable<T>(input: Structure<T>): Structure<T | null>;
+    /**
+     * Creates a Structure that validates a value is one of a set of literals
+     *
+     * ```js
+     * Structure.enum(['a string', 42, false])
+     * ```
+     */
+    static enum<T extends (string | number | boolean)[]>(values: T): Structure<string | number | boolean>;
+    /**
+     * Creates a Structure that validates a value is the `undefined` value
+     *
+     * ```js
+     * Structure.undefined()
+     * ```
+     */
+    static undefined(): Structure<undefined>;
+    /**
+     * Creates a Structure that validates another structure or is not defined
+     *
+     * ```js
+     * Structure.optional(Structure.string())
+     * ```
+     */
+    static optional<T>(input: Structure<T>): Structure<T | undefined>;
 }
 //# sourceMappingURL=structure.d.ts.map

package/config/structure.d.ts.map

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

package/config/structure.js

@@ -310,6 +310,152 @@ export class Structure {
             throw new Structure.Error("Does not match any types in the union", context?.path, errors);
         });
     }
+    /**
+     * @unstable
+     *
+     * Attempts to create a Structure from a parsed [JSON Schema](https://json-schema.org/specification) value.
+     * This is implemented on a as-needed bases, currently it supports:
+     * - "const" → `Structure.literal`
+     * - type=string → `Structure.string`
+     * - type=number → `Structure.number`
+     * - type=boolean → `Structure.boolean`
+     * - type=array → "items" are recursively parsed and put into a `Structure.array`
+     * - type=object → "properties" are recursively parsed and put into a `Structure.object`
+     * - anyOf → `Structure.union`
+     *
+     * ```js
+     * Structure.fromJSONSchema({ type: "string" })
+     * Structure.fromJSONSchema({ type: "number" })
+     * Structure.fromJSONSchema({ type: "boolean" })
+     * Structure.fromJSONSchema({
+     *   type: "object",
+     *   properties: {
+     *     name: { type:"string" },
+     *     age: { type: "number" }
+     *   },
+     *   required: ["name"]
+     * })
+     * Structure.fromJSONSchema({ type: "array", items: { type: "string" } })
+     * Structure.fromJSONSchema({
+     *   anyOf: [
+     *     { type: "string" },
+     *     { type: "number" }
+     *   ]
+     * });
+     * ```
+     *
+     * notes
+     * - array "prefixItems" are not supported, maybe they could be mapped to tuples?
+     */
+    static fromJSONSchema(schema) {
+        if (schema.const)
+            return Structure.literal(schema.const);
+        if (schema.type === "string")
+            return Structure.string(schema.default);
+        if (schema.type === "number")
+            return Structure.number(schema.default);
+        if (schema.type === "boolean")
+            return Structure.boolean(schema.default);
+        if (schema.type === "array") {
+            return Structure.array(Structure.fromJSONSchema(schema.items));
+        }
+        if (schema.type === "object" && typeof schema.properties === "object") {
+            const fields = {};
+            const required = new Set(schema.required ?? []);
+            for (const [key, childSchema] of Object.entries(schema.properties)) {
+                const childStruct = Structure.fromJSONSchema(childSchema);
+                fields[key] = required.has(key)
+                    ? childStruct
+                    : Structure.optional(childStruct);
+            }
+            return Structure.object(fields);
+        }
+        if (Array.isArray(schema.anyOf)) {
+            return Structure.union(schema.anyOf.map((t) => Structure.fromJSONSchema(t)));
+        }
+        throw new TypeError("Unknown schema");
+    }
+    /**
+     * @unstable
+     *
+     * Creates a Structure for arrays where each index has a different validation
+     *
+     * ```js
+     * Structure.tuple([Structure.string(), Structure.number()])
+     * ```
+     */
+    static tuple(types) {
+        const schema = {
+            type: "array",
+            prefixItems: types.map((t) => t.schema),
+        };
+        return new Structure(schema, (value, context) => {
+            if (!Array.isArray(value))
+                throw new Error("Not an array");
+            if (value.length !== types.length)
+                throw new Error("Incorrect length");
+            let output = [];
+            let errors = [];
+            for (let i = 0; i < types.length; i++) {
+                const childContext = _nestContext(context, `${i}`);
+                try {
+                    output.push(types[i].process(value[i], childContext));
+                }
+                catch (error) {
+                    errors.push(Structure.Error.chain(error, childContext));
+                }
+            }
+            if (errors.length > 0) {
+                throw new Structure.Error("Tuple value does not match schema", context.path, errors);
+            }
+            return output;
+        });
+    }
+    /**
+     * @unstable
+     *
+     * Creates a Structure for objects that map a key to a common type of value
+     *
+     * ```js
+     * Structure.record(Structure.string(), Structure.number())
+     * Structure.record(
+     *   Structure.string(),
+     *   Structure.object({ name: Structure.string() })
+     * )
+     * Structure.record(
+     *   Structure.enum(["name", "address", "emailAddress"]),
+     *   Structure.string()
+     * )
+     * ```
+     */
+    static record(keyStruct, valueStruct) {
+        const schema = {
+            type: "object",
+        };
+        return new Structure(schema, (value, context) => {
+            if (typeof value !== "object")
+                throw new Error("Not an object");
+            const output = {};
+            const errors = [];
+            for (const entry of Object.entries(value)) {
+                try {
+                    const ctx = _nestContext(context, entry[0]);
+                    output[keyStruct.process(entry[0], ctx)] = valueStruct.process(entry[1], ctx);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length > 0) {
+                throw new Structure.Error("Invalid record", context.path, errors);
+            }
+            for (const key in output) {
+                if (output[key] === undefined)
+                    delete output[key];
+            }
+            return output;
+        });
+    }
     /**
      * Define a Structure to validate the value is `null`
      *
@@ -408,4 +554,49 @@ export class Structure {
             throw new Error("not a Date");
         });
     }
+    /**
+     * Creates a Structure that validates a value is either another structure or a null value
+     *
+     * ```js
+     * Structure.nullable(Structure.string())
+     * ```
+     */
+    static nullable(input) {
+        return Structure.union([Structure.null(), input]);
+    }
+    /**
+     * Creates a Structure that validates a value is one of a set of literals
+     *
+     * ```js
+     * Structure.enum(['a string', 42, false])
+     * ```
+     */
+    static enum(values) {
+        return Structure.union(values.map((v) => Structure.literal(v)));
+    }
+    /**
+     * Creates a Structure that validates a value is the `undefined` value
+     *
+     * ```js
+     * Structure.undefined()
+     * ```
+     */
+    static undefined() {
+        return new Structure({}, (value) => {
+            if (value !== undefined)
+                throw new Error('value is not "undefined"');
+            else
+                return undefined;
+        });
+    }
+    /**
+     * Creates a Structure that validates another structure or is not defined
+     *
+     * ```js
+     * Structure.optional(Structure.string())
+     * ```
+     */
+    static optional(input) {
+        return Structure.union([input, Structure.undefined()]);
+    }
 }

package/config/structure.test.js

@@ -516,6 +516,117 @@ describe("Structure", () => {
 		});
 	});
 
+	describe("fromJSONSchema", () => {
+		it("parses constants", () => {
+			const result = Structure.fromJSONSchema({ const: 42 });
+			assertEquals(result.process(42), 42);
+		});
+		it("parses strings", () => {
+			const result = Structure.fromJSONSchema({ type: "string" });
+			assertEquals(result.process("Geoff Testington"), "Geoff Testington");
+		});
+		it("parses numbers", () => {
+			const result = Structure.fromJSONSchema({ type: "number" });
+			assertEquals(result.process(42), 42);
+		});
+		it("parses booleans", () => {
+			const result = Structure.fromJSONSchema({ type: "boolean" });
+			assertEquals(result.process(false), false);
+		});
+		it("parses arrays", () => {
+			const result = Structure.fromJSONSchema({
+				type: "array",
+				items: { type: "string" },
+			});
+			assertEquals(result.process(["A", "B", "C"]), ["A", "B", "C"]);
+		});
+		it("parses objects", () => {
+			const result = Structure.fromJSONSchema({
+				type: "object",
+				properties: { name: { type: "string" } },
+				required: ["name"],
+			});
+			assertEquals(result.process({ name: "Geoff" }), { name: "Geoff" });
+		});
+		it("parses objects with optionals", () => {
+			const result = Structure.fromJSONSchema({
+				type: "object",
+				properties: { name: { type: "string" } },
+			});
+			assertEquals(result.process({}), {});
+		});
+		it("parses unions", () => {
+			const result = Structure.fromJSONSchema({
+				anyOf: [{ type: "string" }, { type: "number" }],
+			});
+			assertEquals(result.process("Geoff Testington"), "Geoff Testington");
+			assertEquals(result.process(42), 42);
+		});
+		it("throws for unknown", () => {
+			assertThrows(() => Structure.fromJSONSchema({}));
+		});
+	});
+
+	describe("tuple", () => {
+		const struct = Structure.tuple([
+			Structure.string(),
+			Structure.number(),
+			Structure.literal("magic"),
+		]);
+
+		it("allows matching arrays", () => {
+			assertEquals(struct.process(["Geoff T", 42, "magic"]), [
+				"Geoff T",
+				42,
+				"magic",
+			]);
+		});
+		it("blocks subsets", () => {
+			assertThrows(() => struct.process(["Geoff T", 42]));
+		});
+		it("blocks invalid", () => {
+			assertThrows(() => struct.process([42, "Geoff T", new Date()]));
+		});
+	});
+
+	describe("record", () => {
+		it("allows matching key-value pairs", () => {
+			const struct = Structure.record(Structure.string(), Structure.number());
+			const value = struct.process({ age: 42 });
+			assertEquals(value, { age: 42 });
+		});
+		it("allows enum keys", () => {
+			const struct = Structure.record(
+				Structure.enum(["name", "pet"]),
+				Structure.string(),
+			);
+			const value = struct.process({ name: "Geoff T" });
+			assertEquals(value, { name: "Geoff T" });
+		});
+		it("blocks invalid keys", () => {
+			const struct = Structure.record(
+				Structure.literal("name"),
+				Structure.string(),
+			);
+
+			assertThrows(
+				() => struct.process({ pet: "Hugo" }),
+				(error) => error instanceof Structure.Error,
+			);
+		});
+		it("blocks invalid values", () => {
+			const struct = Structure.record(
+				Structure.literal("name"),
+				Structure.string(),
+			);
+
+			assertThrows(
+				() => struct.process({ name: 119 }),
+				(error) => error instanceof Structure.Error,
+			);
+		});
+	});
+
 	describe("null", () => {
 		const struct = Structure.null();
 

package/config/structure.ts

@@ -360,6 +360,162 @@ export class Structure<T> {
 		});
 	}
 
+	/**
+	 * @unstable
+	 *
+	 * Attempts to create a Structure from a parsed [JSON Schema](https://json-schema.org/specification) value.
+	 * This is implemented on a as-needed bases, currently it supports:
+	 * - "const" → `Structure.literal`
+	 * - type=string → `Structure.string`
+	 * - type=number → `Structure.number`
+	 * - type=boolean → `Structure.boolean`
+	 * - type=array → "items" are recursively parsed and put into a `Structure.array`
+	 * - type=object → "properties" are recursively parsed and put into a `Structure.object`
+	 * - anyOf → `Structure.union`
+	 *
+	 * ```js
+	 * Structure.fromJSONSchema({ type: "string" })
+	 * Structure.fromJSONSchema({ type: "number" })
+	 * Structure.fromJSONSchema({ type: "boolean" })
+	 * Structure.fromJSONSchema({
+	 *   type: "object",
+	 *   properties: {
+	 *     name: { type:"string" },
+	 *     age: { type: "number" }
+	 *   },
+	 *   required: ["name"]
+	 * })
+	 * Structure.fromJSONSchema({ type: "array", items: { type: "string" } })
+	 * Structure.fromJSONSchema({
+	 *   anyOf: [
+	 *     { type: "string" },
+	 *     { type: "number" }
+	 *   ]
+	 * });
+	 * ```
+	 *
+	 * notes
+	 * - array "prefixItems" are not supported, maybe they could be mapped to tuples?
+	 */
+	static fromJSONSchema(schema: any): Structure<any> {
+		if (schema.const) return Structure.literal(schema.const);
+		if (schema.type === "string") return Structure.string(schema.default);
+		if (schema.type === "number") return Structure.number(schema.default);
+		if (schema.type === "boolean") return Structure.boolean(schema.default);
+		if (schema.type === "array") {
+			return Structure.array(Structure.fromJSONSchema(schema.items));
+		}
+		if (schema.type === "object" && typeof schema.properties === "object") {
+			const fields: any = {};
+			const required = new Set(schema.required ?? []);
+			for (const [key, childSchema] of Object.entries(schema.properties)) {
+				const childStruct = Structure.fromJSONSchema(childSchema);
+				fields[key] = required.has(key)
+					? childStruct
+					: Structure.optional(childStruct);
+			}
+			return Structure.object(fields);
+		}
+		if (Array.isArray(schema.anyOf)) {
+			return Structure.union(
+				schema.anyOf.map((t: any) => Structure.fromJSONSchema(t)),
+			);
+		}
+		throw new TypeError("Unknown schema");
+	}
+
+	/**
+	 * @unstable
+	 *
+	 * Creates a Structure for arrays where each index has a different validation
+	 *
+	 * ```js
+	 * Structure.tuple([Structure.string(), Structure.number()])
+	 * ```
+	 */
+	static tuple<const T extends Structure<any>[]>(
+		types: T,
+	): Structure<InferObject<T>> {
+		const schema = {
+			type: "array",
+			prefixItems: types.map((t) => t.schema),
+		};
+		return new Structure(schema, (value, context) => {
+			if (!Array.isArray(value)) throw new Error("Not an array");
+			if (value.length !== types.length) throw new Error("Incorrect length");
+
+			let output: InferObject<T> = [] as any;
+			let errors: any[] = [];
+			for (let i = 0; i < types.length; i++) {
+				const childContext = _nestContext(context, `${i}`);
+				try {
+					output.push(types[i].process(value[i], childContext));
+				} catch (error) {
+					errors.push(Structure.Error.chain(error, childContext));
+				}
+			}
+			if (errors.length > 0) {
+				throw new Structure.Error(
+					"Tuple value does not match schema",
+					context.path,
+					errors,
+				);
+			}
+			return output;
+		});
+	}
+
+	/**
+	 * @unstable
+	 *
+	 * Creates a Structure for objects that map a key to a common type of value
+	 *
+	 * ```js
+	 * Structure.record(Structure.string(), Structure.number())
+	 * Structure.record(
+	 *   Structure.string(),
+	 *   Structure.object({ name: Structure.string() })
+	 * )
+	 * Structure.record(
+	 *   Structure.enum(["name", "address", "emailAddress"]),
+	 *   Structure.string()
+	 * )
+	 * ```
+	 */
+	static record<K extends string, V>(
+		keyStruct: Structure<K>,
+		valueStruct: Structure<V>,
+	): Structure<Record<K, V>> {
+		const schema = {
+			type: "object",
+		};
+		return new Structure<Record<K, V>>(schema, (value, context) => {
+			if (typeof value !== "object") throw new Error("Not an object");
+
+			const output: any = {};
+			const errors: any[] = [];
+			for (const entry of Object.entries(value as any)) {
+				try {
+					const ctx = _nestContext(context, entry[0]);
+					output[keyStruct.process(entry[0], ctx)] = valueStruct.process(
+						entry[1],
+						ctx,
+					);
+				} catch (error) {
+					errors.push(error as Error);
+				}
+			}
+			if (errors.length > 0) {
+				throw new Structure.Error("Invalid record", context.path, errors);
+			}
+			for (const key in output) {
+				if (output[key] === undefined) delete output[key];
+			}
+
+			return output;
+		});
+	}
+
 	/**
 	 * Define a Structure to validate the value is `null`
 	 *
@@ -473,4 +629,51 @@ export class Structure<T> {
 			throw new Error("not a Date");
 		});
 	}
+
+	/**
+	 * Creates a Structure that validates a value is either another structure or a null value
+	 *
+	 * ```js
+	 * Structure.nullable(Structure.string())
+	 * ```
+	 */
+	static nullable<T>(input: Structure<T>) {
+		return Structure.union([Structure.null(), input]);
+	}
+
+	/**
+	 * Creates a Structure that validates a value is one of a set of literals
+	 *
+	 * ```js
+	 * Structure.enum(['a string', 42, false])
+	 * ```
+	 */
+	static enum<T extends (string | number | boolean)[]>(values: T) {
+		return Structure.union(values.map((v) => Structure.literal(v)));
+	}
+
+	/**
+	 * Creates a Structure that validates a value is the `undefined` value
+	 *
+	 * ```js
+	 * Structure.undefined()
+	 * ```
+	 */
+	static undefined() {
+		return new Structure<undefined>({}, (value) => {
+			if (value !== undefined) throw new Error('value is not "undefined"');
+			else return undefined;
+		});
+	}
+
+	/**
+	 * Creates a Structure that validates another structure or is not defined
+	 *
+	 * ```js
+	 * Structure.optional(Structure.string())
+	 * ```
+	 */
+	static optional<T>(input: Structure<T>) {
+		return Structure.union([input, Structure.undefined()]);
+	}
 }

package/core/terminator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminator.d.ts","sourceRoot":"","sources":["terminator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IACjC,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;IAEhB,qCAAqC;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,4DAA4D;IAC5D,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAErE,oEAAoE;IACpE,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3D;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC;AAExD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC;AAK7C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IACtB,KAAK,EAAE,eAAe,CAAa;IACnC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,YAAY,CAAC;gBAET,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,YAAY;IAK5D;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE,gBAAgB;IAM7B;;;;;;;;;;OAUG;IACG,SAAS,CAAC,KAAK,EAAE,gBAAgB;IAevC;;;;;;;;;OASG;IACH,WAAW,IAAI,QAAQ;IAOvB;;;;;;;;;;;;;OAaG;IACG,cAAc;CAGpB"}
+{"version":3,"file":"terminator.d.ts","sourceRoot":"","sources":["terminator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IACjC,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;IAEhB,qCAAqC;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,4DAA4D;IAC5D,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAErE,oEAAoE;IACpE,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3D;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC;AAExD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC;AAK7C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IACtB,KAAK,EAAE,eAAe,CAAa;IACnC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,YAAY,CAAC;gBAET,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,YAAY;IAK5D;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE,gBAAgB;IAM7B;;;;;;;;;;OAUG;IACG,SAAS,CAAC,KAAK,EAAE,gBAAgB;IAevC;;;;;;;;;OASG;IACH,WAAW,IAAI,QAAQ;IAOvB;;;;;;;;;;;;;OAaG;IACG,cAAc;CAWpB"}