@proseql/rest 0.1.0

package/dist/query-params.js

@@ -0,0 +1,380 @@
+/**
+ * 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
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Reserved parameter names that are not field filters.
+ */
+const RESERVED_PARAMS = new Set(["sort", "limit", "offset", "select"]);
+/**
+ * Valid comparison operators for filter syntax.
+ */
+const VALID_OPERATORS = new Set([
+    "$eq",
+    "$ne",
+    "$gt",
+    "$gte",
+    "$lt",
+    "$lte",
+    "$in",
+    "$nin",
+    "$startsWith",
+    "$endsWith",
+    "$contains",
+    "$search",
+    "$all",
+    "$size",
+]);
+// ============================================================================
+// Main Parser
+// ============================================================================
+/**
+ * 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 const parseQueryParams = (query) => {
+    const where = {};
+    let sort;
+    let limit;
+    let offset;
+    let select;
+    for (const [key, value] of Object.entries(query)) {
+        const strValue = normalizeValue(value);
+        // Handle reserved parameters
+        if (key === "sort" && strValue) {
+            sort = parseSortParam(strValue);
+            continue;
+        }
+        if (key === "limit" && strValue) {
+            const parsed = Number.parseInt(strValue, 10);
+            if (!Number.isNaN(parsed) && parsed >= 0) {
+                limit = parsed;
+            }
+            continue;
+        }
+        if (key === "offset" && strValue) {
+            const parsed = Number.parseInt(strValue, 10);
+            if (!Number.isNaN(parsed) && parsed >= 0) {
+                offset = parsed;
+            }
+            continue;
+        }
+        if (key === "select" && strValue) {
+            select = parseSelectParam(strValue);
+            continue;
+        }
+        // Skip reserved params that were handled above
+        if (RESERVED_PARAMS.has(key)) {
+            continue;
+        }
+        // Check for operator syntax: field[$op]=value
+        const operatorMatch = key.match(/^(.+)\[(\$[a-zA-Z]+)\]$/);
+        if (operatorMatch) {
+            const [, field, operator] = operatorMatch;
+            if (field && operator && VALID_OPERATORS.has(operator)) {
+                parseOperatorFilter(where, field, operator, strValue);
+                continue;
+            }
+        }
+        // Simple equality filter
+        if (strValue !== undefined) {
+            where[key] = coerceValue(strValue);
+        }
+    }
+    return {
+        where,
+        ...(sort !== undefined && { sort }),
+        ...(limit !== undefined && { limit }),
+        ...(offset !== undefined && { offset }),
+        ...(select !== undefined && { select }),
+    };
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Normalize a query parameter value to a string or undefined.
+ * Arrays are joined with commas (for $in syntax or multi-value params).
+ */
+const normalizeValue = (value) => {
+    if (typeof value === "string") {
+        return value || undefined;
+    }
+    // Value is ReadonlyArray<string>
+    return value.length > 0 ? value.join(",") : undefined;
+};
+/**
+ * Parse the sort parameter into a sort configuration.
+ *
+ * Supports single field (`year:desc`) or multiple fields (`year:desc,title:asc`).
+ * Defaults to ascending if direction is not specified.
+ */
+const parseSortParam = (value) => {
+    const sort = {};
+    const parts = value.split(",");
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const colonIndex = trimmed.lastIndexOf(":");
+        if (colonIndex === -1) {
+            // No direction specified, default to asc
+            sort[trimmed] = "asc";
+        }
+        else {
+            const field = trimmed.slice(0, colonIndex);
+            const direction = trimmed.slice(colonIndex + 1).toLowerCase();
+            if (field && (direction === "asc" || direction === "desc")) {
+                sort[field] = direction;
+            }
+            else if (field) {
+                // Invalid direction, default to asc
+                sort[field] = "asc";
+            }
+        }
+    }
+    return sort;
+};
+/**
+ * Parse the select parameter into an array of field names.
+ */
+const parseSelectParam = (value) => {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+};
+/**
+ * Parse an operator filter and add it to the where clause.
+ *
+ * Handles type coercion based on the operator:
+ * - $gt, $gte, $lt, $lte, $size: numeric coercion
+ * - $in, $nin: array coercion (comma-separated values)
+ * - $all: array coercion
+ */
+const parseOperatorFilter = (where, field, operator, value) => {
+    if (value === undefined)
+        return;
+    // Get or create the operator object for this field
+    const existing = where[field];
+    const operatorObj = typeof existing === "object" && existing !== null
+        ? existing
+        : {};
+    // Coerce value based on operator
+    let coercedValue;
+    switch (operator) {
+        case "$gt":
+        case "$gte":
+        case "$lt":
+        case "$lte":
+        case "$size":
+            // Numeric operators - attempt numeric coercion
+            coercedValue = coerceNumeric(value);
+            break;
+        case "$in":
+        case "$nin":
+        case "$all":
+            // Array operators - split by comma and coerce each element
+            coercedValue = value.split(",").map((v) => coerceValue(v.trim()));
+            break;
+        default:
+            // String operators and others - coerce as regular value
+            coercedValue = coerceValue(value);
+    }
+    operatorObj[operator] = coercedValue;
+    where[field] = operatorObj;
+};
+/**
+ * Coerce a string value to its appropriate type.
+ *
+ * - Numeric strings become numbers
+ * - "true" and "false" become booleans
+ * - Everything else remains a string
+ */
+const coerceValue = (value) => {
+    // Boolean coercion
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    // Numeric coercion (only for values that look numeric)
+    const numValue = coerceNumeric(value);
+    if (typeof numValue === "number")
+        return numValue;
+    return value;
+};
+/**
+ * Attempt to coerce a string to a number.
+ * Returns the original string if it's not a valid number.
+ */
+const coerceNumeric = (value) => {
+    // Don't coerce empty strings or whitespace-only strings
+    if (!value.trim())
+        return value;
+    // Try integer first
+    const intValue = Number.parseInt(value, 10);
+    if (!Number.isNaN(intValue) && intValue.toString() === value) {
+        return intValue;
+    }
+    // Try float
+    const floatValue = Number.parseFloat(value);
+    if (!Number.isNaN(floatValue) && floatValue.toString() === value) {
+        return floatValue;
+    }
+    return value;
+};
+/**
+ * Reserved parameter names for aggregate queries.
+ */
+const AGGREGATE_PARAMS = new Set([
+    "count",
+    "sum",
+    "avg",
+    "min",
+    "max",
+    "groupBy",
+]);
+/**
+ * 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 const parseAggregateParams = (query) => {
+    const result = {};
+    const where = {};
+    for (const [key, value] of Object.entries(query)) {
+        const strValue = normalizeValue(value);
+        if (strValue === undefined)
+            continue;
+        // Handle aggregate-specific parameters
+        if (key === "count" && strValue.toLowerCase() === "true") {
+            result.count = true;
+            continue;
+        }
+        if (key === "sum" || key === "avg" || key === "min" || key === "max") {
+            const fields = parseFieldListParam(strValue);
+            result[key] = fields.length === 1 ? fields[0] : fields;
+            continue;
+        }
+        if (key === "groupBy") {
+            const fields = parseFieldListParam(strValue);
+            result.groupBy = fields.length === 1 ? fields[0] : fields;
+            continue;
+        }
+        // Skip aggregate params that were handled above
+        if (AGGREGATE_PARAMS.has(key)) {
+            continue;
+        }
+        // Check for operator syntax: field[$op]=value
+        const operatorMatch = key.match(/^(.+)\[(\$[a-zA-Z]+)\]$/);
+        if (operatorMatch) {
+            const [, field, operator] = operatorMatch;
+            if (field && operator && VALID_OPERATORS.has(operator)) {
+                parseOperatorFilter(where, field, operator, strValue);
+                continue;
+            }
+        }
+        // Simple equality filter
+        where[key] = coerceValue(strValue);
+    }
+    // Add where clause if any filters were specified
+    if (Object.keys(where).length > 0) {
+        result.where = where;
+    }
+    // If no aggregations were specified, default to count
+    if (result.count === undefined &&
+        result.sum === undefined &&
+        result.avg === undefined &&
+        result.min === undefined &&
+        result.max === undefined) {
+        result.count = true;
+    }
+    return result;
+};
+/**
+ * Parse a comma-separated field list parameter.
+ */
+const parseFieldListParam = (value) => {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+};
+//# sourceMappingURL=query-params.js.map

package/dist/query-params.js.map

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

package/dist/relationship-routes.d.ts

@@ -0,0 +1,82 @@
+/**
+ * REST Relationship Route Generation for proseql databases.
+ *
+ * Generates framework-agnostic HTTP handlers for relationship sub-routes
+ * derived from collection relationship definitions in the DatabaseConfig.
+ *
+ * For `ref` relationships (e.g., books.author), generates:
+ *   GET /books/:id/author — returns the related author entity
+ *
+ * For `inverse` relationships (e.g., authors.books), generates:
+ *   GET /authors/:id/books — returns related book entities
+ *
+ * @module
+ */
+import type { DatabaseConfig, GenerateDatabase, GenerateDatabaseWithPersistence } from "@proseql/core";
+import type { RouteDescriptor } from "./handlers.js";
+/**
+ * Relationship definition as found in collection config.
+ */
+interface RelationshipDef {
+    readonly type: "ref" | "inverse";
+    readonly target: string;
+    readonly foreignKey?: string;
+}
+/**
+ * Information about a relationship route to be generated.
+ */
+interface RelationshipRouteInfo {
+    /** The source collection name (e.g., "books") */
+    readonly sourceCollection: string;
+    /** The relationship name (e.g., "author") */
+    readonly relationshipName: string;
+    /** The relationship definition */
+    readonly relationship: RelationshipDef;
+}
+/**
+ * Extract all relationship definitions from a database configuration.
+ *
+ * Iterates over all collections in the config and extracts relationship
+ * metadata for each defined relationship.
+ *
+ * @param config - The database configuration
+ * @returns Array of relationship route info objects
+ */
+export declare const extractRelationships: <Config extends DatabaseConfig>(config: Config) => ReadonlyArray<RelationshipRouteInfo>;
+/**
+ * Create REST handlers for all relationship routes in a database.
+ *
+ * Generates sub-routes for navigating relationships:
+ * - `ref` relationships: `GET /:collection/:id/:relationshipName`
+ * - `inverse` relationships: `GET /:collection/:id/:relationshipName`
+ *
+ * @param config - The database configuration defining collections and relationships
+ * @param db - An EffectDatabase or EffectDatabaseWithPersistence instance
+ * @returns Array of route descriptors for relationship routes
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   books: {
+ *     schema: BookSchema,
+ *     relationships: {
+ *       author: { type: "ref", target: "authors", foreignKey: "authorId" },
+ *     },
+ *   },
+ *   authors: {
+ *     schema: AuthorSchema,
+ *     relationships: {
+ *       books: { type: "inverse", target: "books", foreignKey: "authorId" },
+ *     },
+ *   },
+ * } as const
+ *
+ * const routes = createRelationshipRoutes(config, db)
+ * // Generates:
+ * //   GET /books/:id/author  — returns the author of a book
+ * //   GET /authors/:id/books — returns all books by an author
+ * ```
+ */
+export declare const createRelationshipRoutes: <Config extends DatabaseConfig>(config: Config, db: GenerateDatabase<Config> | GenerateDatabaseWithPersistence<Config>) => ReadonlyArray<RouteDescriptor>;
+export {};
+//# sourceMappingURL=relationship-routes.d.ts.map

package/dist/relationship-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-routes.d.ts","sourceRoot":"","sources":["../src/relationship-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACX,cAAc,EACd,gBAAgB,EAChB,+BAA+B,EAC/B,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAA6B,eAAe,EAAE,MAAM,eAAe,CAAC;AAMhF;;GAEG;AACH,UAAU,eAAe;IACxB,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,UAAU,qBAAqB;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kCAAkC;IAClC,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;CACvC;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,SAAS,cAAc,EACjE,QAAQ,MAAM,KACZ,aAAa,CAAC,qBAAqB,CAmBrC,CAAC;AA4HF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,SAAS,cAAc,EACrE,QAAQ,MAAM,EACd,IAAI,gBAAgB,CAAC,MAAM,CAAC,GAAG,+BAA+B,CAAC,MAAM,CAAC,KACpE,aAAa,CAAC,eAAe,CA4C/B,CAAC"}