@proseql/rest 0.1.0

package/dist/relationship-routes.js

@@ -0,0 +1,273 @@
+/**
+ * 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 { Cause, Chunk, Effect, Option, Runtime, Stream } from "effect";
+// ============================================================================
+// Relationship Inspection
+// ============================================================================
+/**
+ * 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 const extractRelationships = (config) => {
+    const relationships = [];
+    for (const [collectionName, collectionConfig] of Object.entries(config)) {
+        const collectionRelationships = collectionConfig.relationships;
+        if (!collectionRelationships)
+            continue;
+        for (const [relationshipName, relationship] of Object.entries(collectionRelationships)) {
+            relationships.push({
+                sourceCollection: collectionName,
+                relationshipName,
+                relationship: relationship,
+            });
+        }
+    }
+    return relationships;
+};
+// ============================================================================
+// Handler Creation
+// ============================================================================
+/**
+ * Create a handler for a `ref` relationship route.
+ *
+ * For a `ref` relationship like `books.author`, this generates a handler for
+ * `GET /books/:id/author` that:
+ * 1. Finds the source entity (book) by ID
+ * 2. Follows the foreign key to the target collection (authors)
+ * 3. Returns the related entity
+ *
+ * @param sourceCollection - The collection object for the source entity
+ * @param targetCollection - The collection object for the target entity
+ * @param foreignKey - The foreign key field name on the source entity
+ * @returns A REST handler function
+ */
+const createRefRelationshipHandler = (
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+sourceCollection, 
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+targetCollection, foreignKey) => {
+    return async (req) => {
+        const { id } = req.params;
+        try {
+            // Find the source entity
+            const findSourceEffect = sourceCollection.findById(id);
+            const sourceEntity = await Effect.runPromise(findSourceEffect);
+            // Get the foreign key value
+            const targetId = sourceEntity[foreignKey];
+            if (targetId === null || targetId === undefined) {
+                // No related entity (foreign key is null/undefined)
+                return { status: 200, body: null };
+            }
+            // Find the related entity
+            const findTargetEffect = targetCollection.findById(targetId);
+            const targetEntity = await Effect.runPromise(findTargetEffect);
+            return { status: 200, body: targetEntity };
+        }
+        catch (error) {
+            if (isTaggedError(error, "NotFoundError")) {
+                return {
+                    status: 404,
+                    body: { error: "Not found", _tag: "NotFoundError" },
+                };
+            }
+            return { status: 500, body: { error: "Internal server error" } };
+        }
+    };
+};
+/**
+ * Create a handler for an `inverse` relationship route.
+ *
+ * For an `inverse` relationship like `authors.books`, this generates a handler
+ * for `GET /authors/:id/books` that:
+ * 1. Verifies the source entity (author) exists
+ * 2. Queries the target collection (books) filtered by the foreign key
+ * 3. Returns the related entities array
+ *
+ * @param sourceCollection - The collection object for the source entity
+ * @param targetCollection - The collection object for the target entity
+ * @param foreignKey - The foreign key field name on the target entity
+ * @returns A REST handler function
+ */
+const createInverseRelationshipHandler = (
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+sourceCollection, 
+// biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+targetCollection, foreignKey) => {
+    return async (req) => {
+        const { id } = req.params;
+        try {
+            // Verify the source entity exists
+            const findSourceEffect = sourceCollection.findById(id);
+            await Effect.runPromise(findSourceEffect);
+            // Query the target collection for related entities
+            const queryConfig = {
+                where: { [foreignKey]: id },
+            };
+            const stream = targetCollection.query(queryConfig);
+            const results = await Effect.runPromise(Stream.runCollect(stream).pipe(Effect.map(Chunk.toReadonlyArray)));
+            return { status: 200, body: results };
+        }
+        catch (error) {
+            if (isTaggedError(error, "NotFoundError")) {
+                return {
+                    status: 404,
+                    body: { error: "Not found", _tag: "NotFoundError" },
+                };
+            }
+            return { status: 500, body: { error: "Internal server error" } };
+        }
+    };
+};
+// ============================================================================
+// Route Generation
+// ============================================================================
+/**
+ * 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 const createRelationshipRoutes = (config, db) => {
+    const routes = [];
+    const relationships = extractRelationships(config);
+    for (const { sourceCollection, relationshipName, relationship, } of relationships) {
+        // Get the source and target collections from the database
+        // biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+        const source = db[sourceCollection];
+        // biome-ignore lint/suspicious/noExplicitAny: Collection type is dynamic
+        const target = db[relationship.target];
+        if (!source || !target) {
+            // Skip if collections don't exist (shouldn't happen with valid config)
+            continue;
+        }
+        const path = `/${sourceCollection}/:id/${relationshipName}`;
+        if (relationship.type === "ref") {
+            // For ref relationships, the foreign key is on the source entity
+            const foreignKey = relationship.foreignKey || `${relationshipName}Id`;
+            routes.push({
+                method: "GET",
+                path,
+                handler: createRefRelationshipHandler(source, target, foreignKey),
+            });
+        }
+        else if (relationship.type === "inverse") {
+            // For inverse relationships, the foreign key is on the target entity
+            // The foreignKey in the config specifies the field on the target that points back
+            const foreignKey = relationship.foreignKey || deriveForeignKey(sourceCollection);
+            routes.push({
+                method: "GET",
+                path,
+                handler: createInverseRelationshipHandler(source, target, foreignKey),
+            });
+        }
+    }
+    return routes;
+};
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Derive a default foreign key name from a collection name.
+ *
+ * Converts plural collection names to singular + "Id":
+ * - "users" → "userId"
+ * - "companies" → "companyId"
+ * - "categories" → "categoryId"
+ *
+ * @param collectionName - The collection name (typically plural)
+ * @returns The derived foreign key field name
+ */
+const deriveForeignKey = (collectionName) => {
+    // Handle "-ies" plural (companies → companyId)
+    if (collectionName.endsWith("ies")) {
+        return `${collectionName.slice(0, -3)}yId`;
+    }
+    // Handle regular "-s" plural (users → userId)
+    if (collectionName.endsWith("s")) {
+        return `${collectionName.slice(0, -1)}Id`;
+    }
+    // Fallback: just append "Id"
+    return `${collectionName}Id`;
+};
+/**
+ * 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=relationship-routes.js.map

package/dist/relationship-routes.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@proseql/rest",
+  "version": "0.1.0",
+  "description": "REST API handlers for ProseQL databases, framework-agnostic",
+  "type": "module",
+  "scripts": {
+    "build": "bunx tsc --build",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "prepublishOnly": "bun run build && bun test"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/simonwjackson/proseql.git",
+    "directory": "packages/rest"
+  },
+  "keywords": [
+    "database",
+    "typescript",
+    "effect",
+    "rest",
+    "api",
+    "plain-text",
+    "type-safe"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@proseql/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "effect": "^3.15.0"
+  }
+}