@proseql/rest 0.1.0

package/dist/handlers.js

@@ -0,0 +1,402 @@
+/**
+ * REST Handler Generation for proseql databases.
+ *
+ * Generates framework-agnostic HTTP handlers for CRUD operations, queries,
+ * and aggregations from a DatabaseConfig and EffectDatabase instance.
+ *
+ * @module
+ */
+import { Cause, Chunk, Effect, Option, Runtime, Stream } from "effect";
+import { parseAggregateParams, parseQueryParams } from "./query-params.js";
+// ============================================================================
+// Handler Factory
+// ============================================================================
+/**
+ * Create REST handlers for all collections in a database.
+ *
+ * Generates framework-agnostic route descriptors that can be adapted to any
+ * HTTP framework (Express, Hono, Bun.serve, etc.).
+ *
+ * Generated routes per collection:
+ * - GET    /:collection           — Query with filters, sort, pagination
+ * - GET    /:collection/:id       — Find by ID
+ * - POST   /:collection           — Create entity
+ * - PUT    /:collection/:id       — Update entity
+ * - DELETE /:collection/:id       — Delete entity
+ * - POST   /:collection/batch     — Create multiple entities
+ * - GET    /:collection/aggregate — Aggregation queries
+ *
+ * @param config - The database configuration defining collections
+ * @param db - An EffectDatabase or EffectDatabaseWithPersistence instance
+ * @returns Array of route descriptors with method, path, and handler
+ *
+ * @example
+ * ```typescript
+ * import { createRestHandlers } from "@proseql/rest"
+ * import { createEffectDatabase } from "@proseql/core"
+ *
+ * const config = {
+ *   books: { schema: BookSchema, relationships: {} },
+ * } as const
+ *
+ * const db = await Effect.runPromise(createEffectDatabase(config, initialData))
+ * const routes = createRestHandlers(config, db)
+ *
+ * // Adapt to your framework:
+ * for (const { method, path, handler } of routes) {
+ *   app[method.toLowerCase()](path, async (req, res) => {
+ *     const response = await handler({
+ *       params: req.params,
+ *       query: req.query,
+ *       body: req.body,
+ *     })
+ *     res.status(response.status).json(response.body)
+ *   })
+ * }
+ * ```
+ */
+export const createRestHandlers = (config, db) => {
+    const routes = [];
+    // Generate routes for each collection
+    for (const collectionName of Object.keys(config)) {
+        // biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic based on config
+        const collection = db[collectionName];
+        // GET /:collection — Query with filters, sort, pagination
+        routes.push({
+            method: "GET",
+            path: `/${collectionName}`,
+            handler: createQueryHandler(collection),
+        });
+        // GET /:collection/aggregate — Aggregation queries
+        // Must be before /:collection/:id to avoid matching "aggregate" as an ID
+        routes.push({
+            method: "GET",
+            path: `/${collectionName}/aggregate`,
+            handler: createAggregateHandler(collection),
+        });
+        // GET /:collection/:id — Find by ID
+        routes.push({
+            method: "GET",
+            path: `/${collectionName}/:id`,
+            handler: createFindByIdHandler(collection),
+        });
+        // POST /:collection — Create entity
+        routes.push({
+            method: "POST",
+            path: `/${collectionName}`,
+            handler: createCreateHandler(collection),
+        });
+        // POST /:collection/batch — Create multiple entities
+        routes.push({
+            method: "POST",
+            path: `/${collectionName}/batch`,
+            handler: createBatchHandler(collection),
+        });
+        // PUT /:collection/:id — Update entity
+        routes.push({
+            method: "PUT",
+            path: `/${collectionName}/:id`,
+            handler: createUpdateHandler(collection),
+        });
+        // DELETE /:collection/:id — Delete entity
+        routes.push({
+            method: "DELETE",
+            path: `/${collectionName}/:id`,
+            handler: createDeleteHandler(collection),
+        });
+    }
+    return routes;
+};
+// ============================================================================
+// Individual Handler Factories
+// ============================================================================
+/**
+ * Create a GET handler for querying a collection.
+ * Parses query parameters and delegates to the collection's query method.
+ */
+const createQueryHandler = (
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+collection) => {
+    return async (req) => {
+        // Parse query params into proseql-compatible query config
+        const queryConfig = parseQueryParams(req.query);
+        const stream = collection.query(queryConfig);
+        const result = await Effect.runPromise(Stream.runCollect(stream).pipe(Effect.map(Chunk.toReadonlyArray)));
+        return { status: 200, body: result };
+    };
+};
+/**
+ * Create a GET handler for finding an entity by ID.
+ */
+const createFindByIdHandler = (
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+collection) => {
+    return async (req) => {
+        const { id } = req.params;
+        try {
+            const findEffect = collection.findById(id);
+            const entity = await Effect.runPromise(findEffect);
+            return { status: 200, body: entity };
+        }
+        catch (error) {
+            // TODO: Map errors via mapErrorToResponse (task 8.1)
+            if (isTaggedError(error, "NotFoundError")) {
+                return {
+                    status: 404,
+                    body: { error: "Not found", _tag: "NotFoundError" },
+                };
+            }
+            return { status: 500, body: { error: "Internal server error" } };
+        }
+    };
+};
+/**
+ * Create a POST handler for creating an entity.
+ */
+const createCreateHandler = (
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+collection) => {
+    return async (req) => {
+        try {
+            const createEffect = collection.create(req.body);
+            const entity = await Effect.runPromise(createEffect);
+            return { status: 201, body: entity };
+        }
+        catch (error) {
+            // TODO: Map errors via mapErrorToResponse (task 8.1)
+            if (isTaggedError(error, "ValidationError")) {
+                return {
+                    status: 400,
+                    body: { error: "Validation error", _tag: "ValidationError" },
+                };
+            }
+            if (isTaggedError(error, "DuplicateKeyError")) {
+                return {
+                    status: 409,
+                    body: { error: "Duplicate key", _tag: "DuplicateKeyError" },
+                };
+            }
+            if (isTaggedError(error, "UniqueConstraintError")) {
+                return {
+                    status: 409,
+                    body: {
+                        error: "Unique constraint violation",
+                        _tag: "UniqueConstraintError",
+                    },
+                };
+            }
+            if (isTaggedError(error, "ForeignKeyError")) {
+                return {
+                    status: 422,
+                    body: { error: "Foreign key violation", _tag: "ForeignKeyError" },
+                };
+            }
+            if (isTaggedError(error, "HookError")) {
+                return {
+                    status: 422,
+                    body: { error: "Hook error", _tag: "HookError" },
+                };
+            }
+            return { status: 500, body: { error: "Internal server error" } };
+        }
+    };
+};
+/**
+ * Create a PUT handler for updating an entity.
+ */
+const createUpdateHandler = (
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+collection) => {
+    return async (req) => {
+        const { id } = req.params;
+        try {
+            const updateEffect = collection.update(id, req.body);
+            const entity = await Effect.runPromise(updateEffect);
+            return { status: 200, body: entity };
+        }
+        catch (error) {
+            // TODO: Map errors via mapErrorToResponse (task 8.1)
+            if (isTaggedError(error, "NotFoundError")) {
+                return {
+                    status: 404,
+                    body: { error: "Not found", _tag: "NotFoundError" },
+                };
+            }
+            if (isTaggedError(error, "ValidationError")) {
+                return {
+                    status: 400,
+                    body: { error: "Validation error", _tag: "ValidationError" },
+                };
+            }
+            if (isTaggedError(error, "UniqueConstraintError")) {
+                return {
+                    status: 409,
+                    body: {
+                        error: "Unique constraint violation",
+                        _tag: "UniqueConstraintError",
+                    },
+                };
+            }
+            if (isTaggedError(error, "HookError")) {
+                return {
+                    status: 422,
+                    body: { error: "Hook error", _tag: "HookError" },
+                };
+            }
+            return { status: 500, body: { error: "Internal server error" } };
+        }
+    };
+};
+/**
+ * Create a DELETE handler for deleting an entity.
+ */
+const createDeleteHandler = (
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+collection) => {
+    return async (req) => {
+        const { id } = req.params;
+        try {
+            const deleteEffect = collection.delete(id);
+            const entity = await Effect.runPromise(deleteEffect);
+            return { status: 200, body: entity };
+        }
+        catch (error) {
+            // TODO: Map errors via mapErrorToResponse (task 8.1)
+            if (isTaggedError(error, "NotFoundError")) {
+                return {
+                    status: 404,
+                    body: { error: "Not found", _tag: "NotFoundError" },
+                };
+            }
+            if (isTaggedError(error, "HookError")) {
+                return {
+                    status: 422,
+                    body: { error: "Hook error", _tag: "HookError" },
+                };
+            }
+            return { status: 500, body: { error: "Internal server error" } };
+        }
+    };
+};
+/**
+ * Create a POST handler for batch creating entities.
+ */
+const createBatchHandler = (
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+collection) => {
+    return async (req) => {
+        try {
+            const batchEffect = collection.createMany(req.body);
+            const result = await Effect.runPromise(batchEffect);
+            return { status: 201, body: result };
+        }
+        catch (error) {
+            // TODO: Map errors via mapErrorToResponse (task 8.1)
+            if (isTaggedError(error, "ValidationError")) {
+                return {
+                    status: 400,
+                    body: { error: "Validation error", _tag: "ValidationError" },
+                };
+            }
+            if (isTaggedError(error, "DuplicateKeyError")) {
+                return {
+                    status: 409,
+                    body: { error: "Duplicate key", _tag: "DuplicateKeyError" },
+                };
+            }
+            if (isTaggedError(error, "UniqueConstraintError")) {
+                return {
+                    status: 409,
+                    body: {
+                        error: "Unique constraint violation",
+                        _tag: "UniqueConstraintError",
+                    },
+                };
+            }
+            if (isTaggedError(error, "ForeignKeyError")) {
+                return {
+                    status: 422,
+                    body: { error: "Foreign key violation", _tag: "ForeignKeyError" },
+                };
+            }
+            if (isTaggedError(error, "HookError")) {
+                return {
+                    status: 422,
+                    body: { error: "Hook error", _tag: "HookError" },
+                };
+            }
+            return { status: 500, body: { error: "Internal server error" } };
+        }
+    };
+};
+/**
+ * Create a GET handler for aggregation queries.
+ * Parses aggregate query parameters and delegates to the collection's aggregate method.
+ *
+ * Supported query parameters:
+ * - count=true: Count entities
+ * - sum=field or sum=field1,field2: Sum numeric fields
+ * - avg=field: Calculate average of numeric fields
+ * - min=field: Find minimum value
+ * - max=field: Find maximum value
+ * - groupBy=field or groupBy=field1,field2: Group results by field(s)
+ * - Filter params: Same as query endpoint (e.g., genre=sci-fi, year[$gte]=1970)
+ *
+ * If no aggregation is specified, defaults to count=true.
+ */
+const createAggregateHandler = (
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+collection) => {
+    return async (req) => {
+        try {
+            // Parse aggregate query params
+            const aggregateConfig = parseAggregateParams(req.query);
+            const aggregateEffect = collection.aggregate(aggregateConfig);
+            const result = await Effect.runPromise(aggregateEffect);
+            return { status: 200, body: result };
+        }
+        catch (_error) {
+            return { status: 500, body: { error: "Internal server error" } };
+        }
+    };
+};
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Extract a tagged error from an unknown error value.
+ *
+ * Effect.runPromise throws a FiberFailure when the Effect fails.
+ * This function extracts the underlying tagged error from the FiberFailure
+ * or returns the error directly if it's already a tagged error.
+ */
+const extractTaggedError = (error) => {
+    // Check if it's a FiberFailure (from Effect.runPromise)
+    if (Runtime.isFiberFailure(error)) {
+        // Get the cause from the FiberFailure using the well-known symbol
+        const causeSymbol = Symbol.for("effect/Runtime/FiberFailure/Cause");
+        const cause = error[causeSymbol];
+        // Extract the failure from the cause
+        const failure = Cause.failureOption(cause);
+        if (Option.isSome(failure)) {
+            const value = failure.value;
+            if (value !== null && typeof value === "object" && "_tag" in value) {
+                return value;
+            }
+        }
+    }
+    // Check if it's already a tagged error
+    if (error !== null && typeof error === "object" && "_tag" in error) {
+        return error;
+    }
+    return null;
+};
+/**
+ * Type guard to check if an error has a specific _tag.
+ * Handles both direct tagged errors and FiberFailure wrappers.
+ */
+const isTaggedError = (error, tag) => {
+    const taggedError = extractTaggedError(error);
+    return taggedError !== null && taggedError._tag === tag;
+};
+//# sourceMappingURL=handlers.js.map

package/dist/handlers.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * proseql-rest — Auto-generated REST API for proseql databases.
+ *
+ * Given a proseql DatabaseConfig, generates framework-agnostic HTTP handlers
+ * for CRUD operations, queries, and aggregations. Includes query parameter
+ * parsing for filters, sorting, pagination, and field selection.
+ *
+ * @example
+ * ```ts
+ * import { createRestHandlers } from "@proseql/rest"
+ * import { createEffectDatabase } from "@proseql/core"
+ *
+ * const handlers = createRestHandlers(config, db)
+ *
+ * // Framework-agnostic handler signature:
+ * // (req: { params, query, body }) => Promise<{ status, body }>
+ *
+ * // Generated routes:
+ * // GET    /books          — query with filters, sort, pagination
+ * // GET    /books/:id      — findById
+ * // POST   /books          — create
+ * // PUT    /books/:id      — update
+ * // DELETE /books/:id      — delete
+ * // POST   /books/batch    — createMany
+ * // GET    /books/aggregate — aggregation
+ * ```
+ *
+ * @module
+ */
+export { createRestHandlers, type HttpMethod, type RestHandler, type RestRequest, type RestResponse, type RouteDescriptor, } from "./handlers.js";
+export { type ParsedAggregateConfig, type ParsedQueryConfig, parseAggregateParams, parseQueryParams, type QueryParams, } from "./query-params.js";
+export { type ErrorResponse, mapErrorToResponse } from "./error-mapping.js";
+export { createRelationshipRoutes, extractRelationships, } from "./relationship-routes.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAMH,OAAO,EACN,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,GACpB,MAAM,eAAe,CAAC;AAMvB,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,WAAW,GAChB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,KAAK,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAM5E,OAAO,EACN,wBAAwB,EACxB,oBAAoB,GACpB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,46 @@
+/**
+ * proseql-rest — Auto-generated REST API for proseql databases.
+ *
+ * Given a proseql DatabaseConfig, generates framework-agnostic HTTP handlers
+ * for CRUD operations, queries, and aggregations. Includes query parameter
+ * parsing for filters, sorting, pagination, and field selection.
+ *
+ * @example
+ * ```ts
+ * import { createRestHandlers } from "@proseql/rest"
+ * import { createEffectDatabase } from "@proseql/core"
+ *
+ * const handlers = createRestHandlers(config, db)
+ *
+ * // Framework-agnostic handler signature:
+ * // (req: { params, query, body }) => Promise<{ status, body }>
+ *
+ * // Generated routes:
+ * // GET    /books          — query with filters, sort, pagination
+ * // GET    /books/:id      — findById
+ * // POST   /books          — create
+ * // PUT    /books/:id      — update
+ * // DELETE /books/:id      — delete
+ * // POST   /books/batch    — createMany
+ * // GET    /books/aggregate — aggregation
+ * ```
+ *
+ * @module
+ */
+// ============================================================================
+// Handler Generation
+// ============================================================================
+export { createRestHandlers, } from "./handlers.js";
+// ============================================================================
+// Query Parameter Parsing
+// ============================================================================
+export { parseAggregateParams, parseQueryParams, } from "./query-params.js";
+// ============================================================================
+// Error Mapping
+// ============================================================================
+export { mapErrorToResponse } from "./error-mapping.js";
+// ============================================================================
+// Relationship Routes
+// ============================================================================
+export { createRelationshipRoutes, extractRelationships, } from "./relationship-routes.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,OAAO,EACN,kBAAkB,GAMlB,MAAM,eAAe,CAAC;AAEvB,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E,OAAO,EAGN,oBAAoB,EACpB,gBAAgB,GAEhB,MAAM,mBAAmB,CAAC;AAE3B,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E,OAAO,EAAsB,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE5E,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO,EACN,wBAAwB,EACxB,oBAAoB,GACpB,MAAM,0BAA0B,CAAC"}

package/dist/query-params.d.ts

@@ -0,0 +1,132 @@
+/**
+ * REST Query Parameter Parsing for proseql databases.
+ *
+ * Converts URL query parameters into proseql-compatible query configurations.
+ * Supports simple equality, operator syntax, sorting, pagination, and field selection.
+ *
+ * @module
+ */
+import type { AggregateConfig } from "@proseql/core";
+/**
+ * Parsed query configuration compatible with proseql's query method.
+ * Contains where clauses, sort configuration, pagination, and field selection.
+ */
+export interface ParsedQueryConfig {
+    /** Where clause with field filters */
+    readonly where: Record<string, unknown>;
+    /** Sort configuration (field -> "asc" | "desc") */
+    readonly sort?: Record<string, "asc" | "desc">;
+    /** Maximum number of results to return */
+    readonly limit?: number;
+    /** Number of results to skip */
+    readonly offset?: number;
+    /** Fields to include in results */
+    readonly select?: ReadonlyArray<string>;
+}
+/**
+ * Input query parameters from URL.
+ * Values can be strings or arrays of strings for repeated parameters.
+ */
+export type QueryParams = Record<string, string | ReadonlyArray<string>>;
+/**
+ * Parse URL query parameters into a proseql-compatible query configuration.
+ *
+ * Supports the following syntax:
+ *
+ * - Simple equality: `?genre=sci-fi` becomes `where: { genre: "sci-fi" }`
+ * - Operator syntax: `?year[$gte]=1970&year[$lt]=2000` becomes `where: { year: { $gte: 1970, $lt: 2000 } }`
+ * - Sorting: `?sort=year:desc` or `?sort=year:desc,title:asc` becomes `sort: { year: "desc", title: "asc" }`
+ * - Pagination: `?limit=10&offset=20` becomes `limit: 10, offset: 20`
+ * - Field selection: `?select=title,year` becomes `select: ["title", "year"]`
+ *
+ * Type coercion is applied:
+ * - Numeric strings become numbers when used with numeric operators ($gt, $gte, $lt, $lte, $size)
+ * - "true" and "false" become booleans
+ * - Comma-separated values in $in/$nin become arrays
+ *
+ * @param query - URL query parameters as key-value pairs
+ * @returns Parsed query configuration for proseql's query method
+ *
+ * @example
+ * ```typescript
+ * // Simple equality
+ * parseQueryParams({ genre: "sci-fi" })
+ * // → { where: { genre: "sci-fi" } }
+ *
+ * // Operator syntax
+ * parseQueryParams({ "year[$gte]": "1970", "year[$lt]": "2000" })
+ * // → { where: { year: { $gte: 1970, $lt: 2000 } } }
+ *
+ * // Combined
+ * parseQueryParams({
+ *   genre: "sci-fi",
+ *   "year[$gte]": "1970",
+ *   sort: "year:desc",
+ *   limit: "10",
+ *   select: "title,year"
+ * })
+ * // → {
+ * //     where: { genre: "sci-fi", year: { $gte: 1970 } },
+ * //     sort: { year: "desc" },
+ * //     limit: 10,
+ * //     select: ["title", "year"]
+ * //   }
+ * ```
+ */
+export declare const parseQueryParams: (query: QueryParams) => ParsedQueryConfig;
+/**
+ * Parsed aggregate configuration compatible with proseql's aggregate method.
+ * Contains aggregation options and optional where clause.
+ */
+export interface ParsedAggregateConfig {
+    /** Count entities */
+    readonly count?: true;
+    /** Field(s) to sum */
+    readonly sum?: string | ReadonlyArray<string>;
+    /** Field(s) to average */
+    readonly avg?: string | ReadonlyArray<string>;
+    /** Field(s) to find minimum */
+    readonly min?: string | ReadonlyArray<string>;
+    /** Field(s) to find maximum */
+    readonly max?: string | ReadonlyArray<string>;
+    /** Field(s) to group by */
+    readonly groupBy?: string | ReadonlyArray<string>;
+    /** Where clause with field filters */
+    readonly where?: Record<string, unknown>;
+}
+/**
+ * Parse URL query parameters into a proseql-compatible aggregate configuration.
+ *
+ * Supports the following syntax:
+ *
+ * - Count: `?count=true` becomes `{ count: true }`
+ * - Sum: `?sum=pages` or `?sum=pages,price` becomes `{ sum: "pages" }` or `{ sum: ["pages", "price"] }`
+ * - Avg: `?avg=rating` becomes `{ avg: "rating" }`
+ * - Min/Max: `?min=year&max=year` becomes `{ min: "year", max: "year" }`
+ * - GroupBy: `?groupBy=genre` or `?groupBy=genre,year` becomes `{ groupBy: "genre" }` or `{ groupBy: ["genre", "year"] }`
+ * - Filters: Same as query params - `?genre=sci-fi` or `?year[$gte]=1970`
+ *
+ * @param query - URL query parameters as key-value pairs
+ * @returns Parsed aggregate configuration for proseql's aggregate method
+ *
+ * @example
+ * ```typescript
+ * // Simple count
+ * parseAggregateParams({ count: "true" })
+ * // → { count: true }
+ *
+ * // Count with filter
+ * parseAggregateParams({ count: "true", genre: "sci-fi" })
+ * // → { count: true, where: { genre: "sci-fi" } }
+ *
+ * // Grouped aggregate
+ * parseAggregateParams({ count: "true", groupBy: "genre" })
+ * // → { count: true, groupBy: "genre" }
+ *
+ * // Multiple aggregations
+ * parseAggregateParams({ count: "true", sum: "pages", avg: "rating", groupBy: "genre" })
+ * // → { count: true, sum: "pages", avg: "rating", groupBy: "genre" }
+ * ```
+ */
+export declare const parseAggregateParams: (query: QueryParams) => AggregateConfig;
+//# sourceMappingURL=query-params.d.ts.map

package/dist/query-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-params.d.ts","sourceRoot":"","sources":["../src/query-params.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAMrD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAExC,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;IAE/C,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,gCAAgC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;AAmCzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,WAAW,KAAG,iBAiErD,CAAC;AAkKF;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC,qBAAqB;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC;IAEtB,sBAAsB;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAE9C,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAE9C,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAE9C,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAE9C,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAElD,sCAAsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,WAAW,KAAG,eA8DzD,CAAC"}