@ultimabase/rest 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @ultimabase/rest
+
+## 0.1.1
+
+### Patch Changes
+
+- The published starter starts: `ultimabase dev` runs `dist/serve.js`, and `@ultimabase/realtime`, which `@ultimabase/graphql` and `@ultimabase/rest` import, is a required peer the starter lists.
+- Updated dependencies
+  - ultimabase@0.1.1
+  - @ultimabase/http@0.1.1
+  - @ultimabase/realtime@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- 0e885c4: The first release: the kernel, its adapters, transports and plugins, the testing helpers and the starter.
+
+### Patch Changes
+
+- Updated dependencies [0e885c4]
+  - @ultimabase/http@0.1.0
+  - @ultimabase/realtime@0.1.0
+  - ultimabase@0.1.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/rest
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A REST API generated from the models and the functions, served by `@ultimabase/http`. It is the GraphQL API in HTTP's grammar: the same names, operators and answers.
+
+Documentation: [REST](https://ultimabase.dev/docs/rest).

package/dist/entries.d.ts

@@ -0,0 +1,38 @@
+import type { ExposedModel, SchemaModel } from 'ultimabase';
+/** A model's key of `.with` (D-129). */
+export type RestWith = {
+    readonly plural?: string;
+    readonly maxTake?: number;
+} | false;
+export type Args = {
+    readonly [key: string]: unknown;
+};
+export type Entry = {
+    readonly exposed: ExposedModel<RestWith>;
+    readonly model: SchemaModel;
+    /** Routed; a hidden model is read and connected through relations only. */
+    readonly visible: boolean;
+    readonly plural: string;
+    /** The rows a list returns without `first`, `last` or `take`. */
+    readonly take: number;
+    readonly maxTake: number;
+};
+/** What every route reads: the models and the plugin's settings. */
+export type Api = {
+    readonly entries: ReadonlyMap<string, Entry>;
+    readonly pagination: 'connection' | 'list';
+    readonly take: number;
+    readonly maxDepth: number;
+    readonly maxRows: number;
+};
+export declare function entryOf(api: Api, model: string): Entry;
+/** Stops startup on a route name GraphQL would refuse as a field name. */
+export declare function checkName(name: string, where: string): string;
+/** `id`, `createdAt` and `updatedAt`, which every model has (D-22). */
+export declare const system: readonly string[];
+/** Each model's entry; two routed models of one plural stop startup. */
+export declare function entriesOf(models: readonly ExposedModel<RestWith>[], options: {
+    readonly take?: number;
+    readonly maxTake?: number;
+}): ReadonlyMap<string, Entry>;
+//# sourceMappingURL=entries.d.ts.map

package/dist/entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../src/entries.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAG3D,wCAAwC;AACxC,MAAM,MAAM,QAAQ,GACnB;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAAA;AAEhE,MAAM,MAAM,IAAI,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAA;AAEtD,MAAM,MAAM,KAAK,GAAG;IACnB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAA;IACxC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,oEAAoE;AACpE,MAAM,MAAM,GAAG,GAAG;IACjB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAC5C,QAAQ,CAAC,UAAU,EAAE,YAAY,GAAG,MAAM,CAAA;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAItD;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,uEAAuE;AACvE,eAAO,MAAM,MAAM,EAAE,SAAS,MAAM,EAAqC,CAAA;AAEzE,wEAAwE;AACxE,wBAAgB,SAAS,CACxB,MAAM,EAAE,SAAS,YAAY,CAAC,QAAQ,CAAC,EAAE,EACzC,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CA4B5B"}

package/dist/entries.js

@@ -0,0 +1,47 @@
+// The models REST serves (D-129): each model's plural and limits, named and
+// bounded as GraphQL names and bounds them (D-107).
+import { plural } from '@ultimabase/http/internal';
+import { Refused } from 'ultimabase';
+export function entryOf(api, model) {
+    const entry = api.entries.get(model);
+    if (entry === undefined)
+        throw new Error(`Unknown model ${model}.`);
+    return entry;
+}
+/** Stops startup on a route name GraphQL would refuse as a field name. */
+export function checkName(name, where) {
+    if (/^[_A-Za-z][_0-9A-Za-z]*$/.test(name) && !name.startsWith('__')) {
+        return name;
+    }
+    throw new Refused(`${where}: ${name} is not a route name.`);
+}
+/** `id`, `createdAt` and `updatedAt`, which every model has (D-22). */
+export const system = ['id', 'createdAt', 'updatedAt'];
+/** Each model's entry; two routed models of one plural stop startup. */
+export function entriesOf(models, options) {
+    const take = options.take ?? 100;
+    const entries = new Map();
+    const owners = new Map();
+    for (const exposed of models) {
+        const name = exposed.schema.name;
+        const own = exposed.with === false ? {} : (exposed.with ?? {});
+        const given = own.plural ?? plural(name.charAt(0).toLowerCase() + name.slice(1));
+        const entry = {
+            exposed,
+            model: exposed.schema,
+            visible: exposed.with !== false,
+            plural: checkName(given, name),
+            take,
+            maxTake: own.maxTake ?? options.maxTake ?? 100,
+        };
+        entries.set(name, entry);
+        if (!entry.visible)
+            continue;
+        const other = given === 'functions' ? 'the functions' : owners.get(given);
+        if (other !== undefined) {
+            throw new Refused(`${name}: the route ${given} is ${other}'s; set .with({ rest: { plural } }).`);
+        }
+        owners.set(given, name);
+    }
+    return entries;
+}

package/dist/fields.d.ts

@@ -0,0 +1,77 @@
+import type { Relay } from '@ultimabase/http/internal';
+import type { Row } from 'ultimabase';
+import type { Api, Args, Entry } from './entries.ts';
+/** A field of the response, in the order the request wrote it. */
+type Out = {
+    readonly kind: 'scalar';
+    readonly name: string;
+    readonly toJSON: ((value: unknown) => unknown) | undefined;
+} | {
+    readonly kind: 'one';
+    readonly name: string;
+    readonly shape: Shape;
+} | {
+    readonly kind: 'many';
+    readonly name: string;
+    readonly shape: Shape;
+    readonly relay: Relay | undefined;
+    /** The rows it asks for, which the row budget counts. */
+    readonly size: number;
+    /** Whether it answers its `totalCount` (D-134). */
+    readonly counted: boolean;
+} | {
+    /** A virtual's rows of a model, re-read by the kernel (D-151). */
+    readonly kind: 'returned';
+    readonly name: string;
+    readonly owner: string;
+    readonly shape: Shape;
+    readonly list: boolean;
+    /** The rows it counts: `take` for a list, as a function's (D-109). */
+    readonly size: number;
+};
+/**
+ * What a row of the response holds. `sorted` is the relations its list's
+ * `orderBy` goes through, each a level of `maxDepth` (D-134).
+ */
+export type Shape = {
+    readonly fields: readonly Out[];
+    readonly sorted?: number;
+};
+/** A row's fields and its relations' reads, as the kernel takes them. */
+export type Read = {
+    readonly read: Args;
+    readonly shape: Shape;
+};
+/**
+ * `id`, the dates, each scalar field a caller other than Master reads, and
+ * each virtual of a scalar without an input (D-151).
+ */
+export declare const defaultShape: (entry: Entry) => Shape;
+/** The virtuals a row holds without `select` (D-151). */
+export declare const defaultVirtuals: (entry: Entry) => readonly string[];
+/** A list's `where`, its dates read; `null` is absent, as in GraphQL. */
+export declare const filterOf: (api: Api, entry: Entry, where: unknown, path: string) => Args;
+/** Reads `select` or `include` as the request wrote them. */
+declare class Reader {
+    #private;
+    constructor(api: Api, master: boolean);
+    /** A row's `select` or `include`, under `path` (`''` at the root). */
+    fields(entry: Entry, args: Args, path: string): Read;
+    /** A list's arguments: its page, filter, order and fields. */
+    list(entry: Entry, args: Args, path: string): Read & {
+        readonly relay: Relay | undefined;
+        readonly size: number;
+    };
+}
+/** The reader of a request's `select` and `include`. */
+export declare const readerOf: (api: Api, master: boolean) => Reader;
+/** The levels of relations a row nests, the row counting one. */
+export declare function depthOf(shape: Shape): number;
+/** The rows the relations of `times` rows may return, as D-107 counts them. */
+export declare function rowsBelow(shape: Shape, times: number): number;
+/** A row as GraphQL returns it: its fields, its relations' pages. */
+export declare function shaped(row: Row, shape: Shape): {
+    [field: string]: unknown;
+};
+export {};
+//# sourceMappingURL=fields.d.ts.map

package/dist/fields.d.ts.map

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

package/dist/fields.js

@@ -0,0 +1,288 @@
+import { connection, pageArgs, pageOf, readable, readableVirtuals, rowOf, rowsOf, } from '@ultimabase/http/internal';
+import { InvalidQuery } from 'ultimabase';
+import { entryOf, system } from './entries.js';
+import { isArgs, whereOf } from './values.js';
+/** The relations an `orderBy` goes through, the deepest path's. */
+function sortDepth(orderBy) {
+    if (Array.isArray(orderBy))
+        return Math.max(0, ...orderBy.map(sortDepth));
+    if (typeof orderBy !== 'object' || orderBy === null)
+        return 0;
+    return Math.max(0, ...Object.values(orderBy).map((value) => typeof value === 'object' && value !== null ? 1 + sortDepth(value) : 0));
+}
+const unknownKey = (path, model) => new InvalidQuery(path, `Unknown key '${path}' on ${model}.`);
+const scalar = (entry, name) => ({
+    kind: 'scalar',
+    name,
+    // A plugin field reads as its toJSON gives (D-122).
+    toJSON: entry.exposed.fieldTypes[name]?.toJSON,
+});
+/**
+ * `id`, the dates, each scalar field a caller other than Master reads, and
+ * each virtual of a scalar without an input (D-151).
+ */
+export const defaultShape = (entry) => ({
+    fields: [
+        ...system.map((name) => scalar(entry, name)),
+        ...readable(entry)
+            .filter((field) => field.kind === 'scalar')
+            .map((field) => scalar(entry, field.name)),
+        ...defaultVirtuals(entry).map((name) => scalar(entry, name)),
+    ],
+});
+/** The virtuals a row holds without `select` (D-151). */
+export const defaultVirtuals = (entry) => readableVirtuals(entry)
+    .filter((virtual) => virtual.default)
+    .map((virtual) => virtual.name);
+// `take` for none or a negative number; above `maxTake`, the list refuses.
+const sizeOf = (entry, asked) => typeof asked === 'number' && asked >= 0
+    ? Math.min(asked, entry.maxTake)
+    : entry.take;
+/** A list's `where`, its dates read; `null` is absent, as in GraphQL. */
+export const filterOf = (api, entry, where, path) => where === undefined || where === null
+    ? {}
+    : {
+        where: isArgs(where)
+            ? whereOf(api, entry.model.name, where, path)
+            : where,
+    };
+/** Reads `select` or `include` as the request wrote them. */
+class Reader {
+    #api;
+    #master;
+    constructor(api, master) {
+        this.#api = api;
+        this.#master = master;
+    }
+    /** A row's `select` or `include`, under `path` (`''` at the root). */
+    fields(entry, args, path) {
+        const at = (key) => (path === '' ? key : `${path}.${key}`);
+        const { select, include } = args;
+        if (select !== undefined && include !== undefined) {
+            throw new InvalidQuery(path, `${at('select')} and include cannot be used together.`);
+        }
+        const base = select === undefined ? 'include' : 'select';
+        const chosen = select ?? include;
+        if (chosen === undefined)
+            return { read: {}, shape: defaultShape(entry) };
+        if (!isArgs(chosen)) {
+            throw new InvalidQuery(at(base), `${at(base)} must be an object.`);
+        }
+        const kernel = base === 'select' ? { id: true } : {};
+        const fields = base === 'select' ? [] : [...defaultShape(entry).fields];
+        // The relations' `totalCount`, each the count of its `where` (D-134).
+        const counts = {};
+        const model = entry.model.name;
+        for (const [name, value] of Object.entries(chosen)) {
+            const where = `${at(base)}.${name}`;
+            const virtual = readableVirtuals(entry).find((each) => each.name === name);
+            if (virtual !== undefined) {
+                if (value === false)
+                    continue;
+                const read = this.#virtual(entry, virtual, value, where);
+                kernel[name] = read.read;
+                // `include` reads a default virtual again, where it is.
+                const known = fields.findIndex((each) => each.name === name);
+                if (known === -1)
+                    fields.push(read.field);
+                else
+                    fields[known] = read.field;
+                continue;
+            }
+            const field = readable(entry).find((each) => each.name === name);
+            const isScalar = field === undefined ? system.includes(name) : field.kind === 'scalar';
+            if ((field === undefined && !isScalar) ||
+                (base === 'include' && isScalar)) {
+                throw unknownKey(where, model);
+            }
+            if (value === false)
+                continue;
+            if (field === undefined || field.kind === 'scalar') {
+                if (value !== true) {
+                    throw new InvalidQuery(where, `${where} must be a boolean.`);
+                }
+                kernel[name] = true;
+                fields.push(scalar(entry, name));
+                continue;
+            }
+            const target = entryOf(this.#api, field.target);
+            const given = value === true ? {} : value;
+            if (!isArgs(given)) {
+                throw new InvalidQuery(where, `${where} must be an object.`);
+            }
+            if (field.kind === 'one') {
+                this.#keys(given, ['select', 'include'], where, model);
+                const nested = this.fields(target, given, where);
+                kernel[name] = nested.read;
+                fields.push({ kind: 'one', name, shape: nested.shape });
+                continue;
+            }
+            // A list has no count (D-134): `totalCount` is unknown there.
+            const pages = this.#api.pagination === 'connection';
+            const { totalCount, ...listed } = given;
+            const many = this.list(target, pages ? listed : given, where);
+            const counted = pages && totalCount === true;
+            if (pages &&
+                totalCount !== undefined &&
+                typeof totalCount !== 'boolean') {
+                const key = `${where}.totalCount`;
+                throw new InvalidQuery(key, `${key} must be true or false.`);
+            }
+            if (counted) {
+                const filter = many.read['where'];
+                counts[name] = filter === undefined ? true : { where: filter };
+            }
+            kernel[name] = many.read;
+            fields.push({
+                kind: 'many',
+                name,
+                shape: many.shape,
+                relay: many.relay,
+                // A count reads the rows it counts, however few the page returns.
+                size: counted ? Math.max(many.size, target.take) : many.size,
+                counted,
+            });
+        }
+        if (Object.keys(counts).length > 0)
+            kernel['_count'] = { select: counts };
+        return { read: { [base]: kernel }, shape: { fields } };
+    }
+    /** A virtual's read: `true` or its input, a model's fields too (D-151). */
+    #virtual(entry, virtual, value, where) {
+        const { name, output } = virtual;
+        if (output.kind !== 'model') {
+            return { read: value, field: scalar(entry, name) };
+        }
+        if (value !== true && !isArgs(value)) {
+            throw new InvalidQuery(where, `${where} must be true or an object.`);
+        }
+        const { select, include, ...input } = value === true ? {} : value;
+        const target = entryOf(this.#api, output.name);
+        const nested = this.fields(target, { select, include }, where);
+        const list = output.form === 'list';
+        return {
+            read: value === true ? true : { ...input, ...nested.read },
+            field: {
+                kind: 'returned',
+                name,
+                owner: `${entry.model.name}.${name}`,
+                shape: nested.shape,
+                list,
+                size: list ? this.#api.take : 1,
+            },
+        };
+    }
+    /** A list's arguments: its page, filter, order and fields. */
+    list(entry, args, path) {
+        const at = (key) => (path === '' ? key : `${path}.${key}`);
+        const paging = pageArgs(this.#api.pagination);
+        const keys = ['select', 'include', 'where', 'orderBy', ...paging];
+        this.#keys(args, keys, path, entry.model.name);
+        const page = pageOf(this.#api.pagination, entry, args, this.#master, at);
+        const { where, orderBy } = args;
+        const nested = this.fields(entry, args, path);
+        const asked = this.#api.pagination === 'list'
+            ? args['take']
+            : (args['last'] ?? args['first']);
+        return {
+            read: {
+                ...nested.read,
+                ...page.read,
+                ...filterOf(this.#api, entry, where, at('where')),
+                ...(orderBy === undefined || orderBy === null ? {} : { orderBy }),
+            },
+            shape: { ...nested.shape, sorted: sortDepth(orderBy) },
+            relay: page.relay,
+            size: sizeOf(entry, asked),
+        };
+    }
+    #keys(args, keys, path, model) {
+        for (const key of Object.keys(args)) {
+            if (!keys.includes(key)) {
+                throw unknownKey(path === '' ? key : `${path}.${key}`, model);
+            }
+        }
+    }
+}
+/** The reader of a request's `select` and `include`. */
+export const readerOf = (api, master) => new Reader(api, master);
+/** The levels of relations a row nests, the row counting one. */
+export function depthOf(shape) {
+    let deepest = shape.sorted ?? 0;
+    for (const field of shape.fields) {
+        if (field.kind !== 'scalar')
+            deepest = Math.max(deepest, depthOf(field.shape));
+    }
+    return 1 + deepest;
+}
+/** The rows the relations of `times` rows may return, as D-107 counts them. */
+export function rowsBelow(shape, times) {
+    let rows = 0;
+    for (const field of shape.fields) {
+        if (field.kind === 'scalar')
+            continue;
+        const each = field.kind === 'one' ? times : times * field.size;
+        rows += each;
+        if (each > 0)
+            rows += rowsBelow(field.shape, each);
+    }
+    return rows;
+}
+/** The count the kernel read of a row's relation (D-134). */
+function countOf(row, name) {
+    const counts = row['_count'];
+    return isArgs(counts) ? counts[name] : undefined;
+}
+/** A virtual's rows of a model, at most `take` under a relation (D-109). */
+function returned(field, value) {
+    if (!field.list) {
+        const row = rowOf(value);
+        return row === undefined ? null : shaped(row, field.shape);
+    }
+    const rows = rowsOf(value);
+    const relates = field.shape.fields.some((each) => each.kind !== 'scalar');
+    if (rows.length > field.size && relates) {
+        throw new RangeError(`${field.owner} returned ${rows.length} rows; a list counts take (${field.size}) rows, so it holds no more under a selected relation.`);
+    }
+    return rows.map((row) => shaped(row, field.shape));
+}
+/** A row as GraphQL returns it: its fields, its relations' pages. */
+export function shaped(row, shape) {
+    const out = {};
+    for (const field of shape.fields) {
+        const value = row[field.name];
+        if (field.kind === 'scalar') {
+            out[field.name] =
+                value === undefined || value === null
+                    ? null
+                    : field.toJSON === undefined
+                        ? value
+                        : field.toJSON(value);
+        }
+        else if (field.kind === 'one') {
+            const target = rowOf(value);
+            out[field.name] =
+                target === undefined ? null : shaped(target, field.shape);
+        }
+        else if (field.kind === 'returned') {
+            out[field.name] = returned(field, value);
+        }
+        else if (value === undefined || value === null) {
+            // Absent when the field's read rule hides it (D-44).
+            out[field.name] = null;
+        }
+        else {
+            const rows = rowsOf(value);
+            const node = (each) => shaped(each, field.shape);
+            if (field.relay === undefined) {
+                out[field.name] = rows.map(node);
+                continue;
+            }
+            const page = connection(rows, field.relay, node);
+            out[field.name] = field.counted
+                ? { ...page, totalCount: countOf(row, field.name) }
+                : page;
+        }
+    }
+    return out;
+}

package/dist/functions.d.ts

@@ -0,0 +1,28 @@
+import type { Routes } from '@ultimabase/http';
+import type { Node } from '@ultimabase/http/internal';
+import type { ExposedFunction } from 'ultimabase';
+import type { Api } from './entries.ts';
+import type { Accepted } from './params.ts';
+import type { Live } from './streams.ts';
+/** A function's key of `.with` (D-129): its route's name, or hidden. */
+export type RestFunctionWith = {
+    readonly name?: string;
+} | false;
+/** A function REST routes, named, and its input's JSON Schema. */
+export type Routed = {
+    readonly fn: ExposedFunction<RestFunctionWith>;
+    readonly owner: string;
+    readonly name: string;
+    readonly input: Node | undefined;
+};
+/**
+ * A GET's parameters: an object input's keys, as GraphQL's arguments, or
+ * one `input`; a string as is, any other value as JSON.
+ */
+export declare function getParams(root: Node | undefined): {
+    readonly accepted: Accepted;
+    readonly flat: boolean;
+};
+/** Each routed function under `${base}/functions` (D-109, D-113). */
+export declare function functionRoutes(app: Routes, api: Api, functions: readonly ExposedFunction<RestFunctionWith>[], base: string, live: Live | undefined): readonly Routed[];
+//# sourceMappingURL=functions.d.ts.map

package/dist/functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../src/functions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAA;AAErD,OAAO,KAAK,EAAkB,eAAe,EAAiB,MAAM,YAAY,CAAA;AAEhF,OAAO,KAAK,EAAE,GAAG,EAAS,MAAM,cAAc,CAAA;AAK9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAG3C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAExC,wEAAwE;AACxE,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAAA;AAIjE,kEAAkE;AAClE,MAAM,MAAM,MAAM,GAAG;IACpB,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAA;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,CAAA;CAChC,CAAA;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,GAAG;IAClD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACtB,CAiBA;AAwED,qEAAqE;AACrE,wBAAgB,cAAc,CAC7B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,SAAS,eAAe,CAAC,gBAAgB,CAAC,EAAE,EACvD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,GAAG,SAAS,GACpB,SAAS,MAAM,EAAE,CAoEnB"}