json-rest-api 0.1.1 → 1.0.1

package/TODO_rest-api-plugin-extras.js

@@ -0,0 +1,142 @@
+
+
+
+
+
+
+
+
+
+
+
+
+/**
+ * Fetches the collection of full "child" resource objects belonging to a parent.
+ * This function calls the related resource link (e.g., GET /api/articles/1/comments).
+ * @param {string} parentType - The type of the parent resource (e.g., "articles").
+ * @param {(string|number)} parentId - The ID of the parent resource.
+ * @param {string} relationshipName - The name of the relationship to fetch (e.g., "comments").
+ * @param {object} [queryParams={}] - Optional. An object to filter, sort, or paginate the **returned child resources**.
+ * @returns {Promise<object>} A Promise that resolves to the JSON:API collection response for the related resources.
+ *
+ * @example
+ * // Get the 10 newest comments for article "123", including each comment's author
+ * const commentsResponse = await api.getRelated('articles', '123', 'comments', {
+ * include: 'author',
+ * sort: '-created-at',
+ * page: { "number": 1, "size": 10 }
+ * });
+ * @see GET /api/articles/123/comments?include=author&sort=-created-at&page[number]=1&page[size]=10
+ * // Example Return Value for commentsResponse:
+ * // {
+ * //   "links": { "self": "/api/articles/123/comments?..." },
+ * //   "data": [
+ * //     { "type": "comments", "id": "456", "attributes": { ... }, "relationships": { ... } }
+ * //   ],
+ * //   "included": [{ "type": "people", "id": "9", "attributes": { ... } }]
+ * // }
+ */
+async function getRelated(parentType, parentId, relationshipName, queryParams = {}) {
+  // Implementation calls GET /api/{parentType}/{parentId}/{relationshipName}
+  console.log(`GET /api/${parentType}/${parentId}/${relationshipName}`, { queryParams });
+  return Promise.resolve({});
+}
+
+/**
+ * Fetches the linkage data only (the `type` and `id` identifiers) for a relationship.
+ * This function calls the relationship link (e.g., GET /api/articles/1/relationships/comments).
+ * @param {string} parentType - The type of the parent resource (e.g., "articles").
+ * @param {(string|number)} parentId - The ID of the parent resource.
+ * @param {string} relationshipName - The name of the relationship to fetch (e.g., "comments").
+ * @returns {Promise<object>} A Promise that resolves to the JSON:API relationship linkage object.
+ *
+ * @example
+ * // Get the linkage data for the author of article "123"
+ * const authorLinkageResponse = await api.getRelationship('articles', '123', 'author');
+ * @see GET /api/articles/123/relationships/author
+ * // Example Return Value for authorLinkageResponse:
+ * // {
+ * //   "links": {
+ * //     "self": "/api/articles/123/relationships/author",
+ * //     "related": "/api/articles/123/author"
+ * //   },
+ * //   "data": { "type": "people", "id": "9" }
+ * // }
+ */
+async function getRelationship(parentType, parentId, relationshipName) {
+  // Implementation calls GET /api/{parentType}/{parentId}/relationships/{relationshipName}
+  console.log(`GET /api/${parentType}/${parentId}/relationships/${relationshipName}`);
+  return Promise.resolve({});
+}
+
+
+/**
+ * Adds one or more links to an existing to-many relationship. This links existing resources; it does not create new ones.
+ * This function sends a POST request to the relationship link.
+ * @param {string} parentType - The type of the parent resource.
+ * @param {(string|number)} parentId - The ID of the parent resource.
+ * @param {string} relationshipName - The name of the relationship to modify.
+ * @param {object[]} linkage - An array of resource identifier objects ({ type, id }) to add to the relationship.
+ * @returns {Promise<void>} A Promise that resolves when the addition is complete. Server returns 204 No Content.
+ *
+ * @example
+ * // Add tags with IDs "5" and "8" to article "123"
+ * await api.postRelationship('articles', '123', 'tags', [
+ * { "type": "tags", "id": "5" },
+ * { "type": "tags", "id": "8" }
+ * ]);
+ * @see POST /api/articles/123/relationships/tags
+ */
+async function postRelationship(parentType, parentId, relationshipName, linkage) {
+  // Implementation calls POST /api/{parentType}/{parentId}/relationships/{relationshipName}
+  console.log(`POST /api/${parentType}/${parentId}/relationships/${relationshipName}`, { data: linkage });
+  return Promise.resolve();
+}
+
+/**
+ * Completely replaces the links in a relationship with a new set of links.
+ * This function sends a PATCH request to the relationship link.
+ * @param {string} parentType - The type of the parent resource.
+ * @param {(string|number)} parentId - The ID of the parent resource.
+ * @param {string} relationshipName - The name of the relationship to modify.
+ * @param {object|object[]|null} linkage - The new, complete set of resource identifier objects ({ type, id }) for the relationship.
+ * @returns {Promise<void>} A Promise that resolves when the replacement is complete. Server returns 204 No Content.
+ *
+ * @example
+ * // Set the tags for article "123" to be ONLY tag "5"
+ * await api.patchRelationship('articles', '123', 'tags', [
+ * { "type": "tags", "id": "5" }
+ * ]);
+ * @see PATCH /api/articles/123/relationships/tags
+ */
+async function patchRelationship(parentType, parentId, relationshipName, linkage) {
+  // Implementation calls PATCH /api/{parentType}/{parentId}/relationships/{relationshipName}
+  console.log(`PATCH /api/${parentType}/${parentId}/relationships/${relationshipName}`, { data: linkage });
+  return Promise.resolve();
+}
+
+/**
+ * Removes one or more links from a to-many relationship. This does not delete the resources themselves.
+ * This function sends a DELETE request to the relationship link.
+ * @param {string} parentType - The type of the parent resource.
+ * @param {(string|number)} parentId - The ID of the parent resource.
+ * @param {string} relationshipName - The name of the relationship to modify.
+ * @param {object[]} linkage - An array of resource identifier objects ({ type, id }) to remove from the relationship.
+ * @returns {Promise<void>} A Promise that resolves when the removal is complete. Server returns 204 No Content.
+ *
+ * @example
+ * // Remove the tag with ID "7" from article "123"
+ * await api.deleteRelationship('articles', '123', 'tags', [
+ * { "type": "tags", "id": "7" }
+ * ]);
+ * @see DELETE /api/articles/123/relationships/tags
+ */
+async function deleteRelationship(parentType, parentId, relationshipName, linkage) {
+  // Implementation calls DELETE /api/{parentType}/{parentId}/relationships/{relationshipName}
+  console.log(`DELETE /api/${parentType}/${parentId}/relationships/${relationshipName}`, { data: linkage });
+  return Promise.resolve();
+}
+
+
+
+

package/connectors_ideas/express-plugin.js

@@ -0,0 +1,120 @@
+/**
+ * http-plugin-express.js
+ * This plugin for Hooked API provides an HTTP layer using the Express.js framework.
+ * It automatically generates JSON:API compliant RESTful routes for each scope
+ * added to the API instance.
+ */
+import { HookedApiError } from './hooked-api.js';
+import { handleApiError } from './error-handler.js';
+
+export const HttpExpressPlugin = {
+  name: 'http-express',
+
+  /**
+   * Installs the HTTP plugin, connecting the API to an Express app.
+   * @param {object} context - The installation context from Hooked API.
+   * @param {object} context.pluginOptions - Options passed during `api.use()`.
+   * @param {Express.Application} context.pluginOptions.http.app - The Express app instance. (Required)
+   * @param {string} [context.pluginOptions.http.prefix='/api'] - The URL prefix for all API routes.
+   * @param {Api} api - The API instance itself.
+   */
+  install(context, api) {
+    const { pluginOptions, log } = context;
+    const httpOptions = pluginOptions.http || {};
+    
+    const { app, prefix = '/api' } = httpOptions;
+
+    if (!app) {
+      throw new HookedApiError(
+        "The 'http-express' plugin requires an Express 'app' instance to be passed in the options. Example: api.use(HttpExpressPlugin, { http: { app: myExpressApp } })",
+        'CONFIGURATION_ERROR'
+      );
+    }
+
+    log.info(`Express HTTP plugin installed. Routes will be prefixed with '${prefix}'.`);
+
+    /**
+     * Creates a generic Express request handler for a specific API method.
+     * This factory function avoids code duplication for route handlers.
+     * @param {string} methodName - The name of the scope method to call (e.g., 'get', 'query').
+     * @returns {Function} An async Express route handler.
+     */
+    const _createRequestHandler = (methodName) => {
+      // This is an async function that Express 5 will handle correctly,
+      // automatically catching promise rejections and passing them to the error handler.
+      return async (req, res, next) => {
+        const { scopeName, id } = req.params;
+
+        try {
+          // 1. Translate Express req into the API method's specific params object.
+          const apiParams = {};
+
+          if (['get', 'put', 'patch', 'delete'].includes(methodName)) {
+            apiParams.id = id;
+          }
+          if (['query', 'get', 'post', 'put', 'patch'].includes(methodName)) {
+            // Express automatically parses simple query strings. For nested objects
+            // like `fields[articles]`, ensure the 'qs' query parser is enabled in your main app.
+            apiParams.queryParams = req.query;
+          }
+          if (['post', 'put', 'patch'].includes(methodName)) {
+            // Assumes `express.json()` body-parser middleware is used on the app.
+            apiParams.inputRecord = req.body;
+          }
+
+          log.debug(`Express request for ${scopeName}.${methodName}`, { id, query: req.query });
+
+          // 2. Execute the corresponding API method
+          const result = await api.scopes[scopeName][methodName](apiParams);
+
+          // 3. Send the successful HTTP response
+          switch (methodName) {
+            case 'post':
+              res.status(201).json(result);
+              break;
+            case 'delete':
+              res.status(204).send();
+              break;
+            default:
+              res.status(200).json(result);
+          }
+        } catch (error) {
+          // 4. Pass any errors to Express's next-tick error handler.
+          next(error);
+        }
+      };
+    };
+
+    /**
+     * Creates all the standard RESTful routes for a given scope.
+     * @param {string} scopeName - The name of the scope to create routes for.
+     */
+    const _createRoutesForScope = (scopeName) => {
+      // Use a new router for each scope to keep things clean.
+      const router = express.Router();
+      const basePath = `/${scopeName}`;
+      const singlePath = `${basePath}/:id`;
+
+      log.info(`Creating Express HTTP routes for scope: '${scopeName}'`);
+
+      router.get('/', _createRequestHandler('query'));
+      router.get('/:id', _createRequestHandler('get'));
+      router.post('/', _createRequestHandler('post'));
+      router.put('/:id', _createRequestHandler('put'));
+      router.patch('/:id', _createRequestHandler('patch'));
+      router.delete('/:id', _createRequestHandler('delete'));
+      
+      // Mount the scope's router on the main app at the correct prefix.
+      app.use(prefix, router);
+    };
+
+    // --- Main Logic: Wrap `addScope` to automate route creation ---
+    const originalAddScope = api.addScope;
+
+    api.addScope = (name, options, extras) => {
+      const result = originalAddScope.call(api, name, options, extras);
+      _createRoutesForScope(name);
+      return result;
+    };
+  }
+};

package/connectors_ideas/fastify.js

@@ -0,0 +1,219 @@
+/**
+ * http-plugin-fastify.js
+ * This plugin for Hooked API provides a high-performance HTTP layer using the Fastify framework.
+ * It automatically generates JSON:API compliant RESTful routes and schemas for each scope.
+ *
+ * You'll need to install dependencies: npm install fastify
+ */
+import { HookedApiError } from './hooked-api.js';
+import { handleFastifyApiError } from './error-handler-fastify.js';
+
+/**
+ * **UPGRADED:** Automatically generates a comprehensive Fastify schema object that conforms
+ * to the full JSON:API specification, including relationships, links, and meta.
+ * @param {string} scopeName - The name of the resource type (e.g., 'articles').
+ * @param {object} scopeOptions - The full options object for the scope.
+ * @returns {object} A complete Fastify schema for all CRUD routes.
+ */
+function _generateFastifySchema(scopeName, scopeOptions = {}) {
+  const appSchema = scopeOptions.schema || {};
+  const relationshipsSchema = scopeOptions.relationships || {};
+
+  // --- Reusable Schema Components ---
+  const metaObject = { type: 'object', additionalProperties: true };
+  const linksObject = {
+    type: 'object',
+    properties: {
+      self: { type: 'string', format: 'uri-reference' },
+      related: { type: 'string', format: 'uri-reference' },
+    }
+  };
+  const resourceIdentifierObject = {
+    type: 'object',
+    required: ['type', 'id'],
+    properties: {
+      type: { type: 'string' },
+      id: { type: 'string' }
+    }
+  };
+
+  // --- Build Attribute Properties from simple schema ---
+  const attributeProperties = {};
+  const requiredAttributes = [];
+  for (const [key, value] of Object.entries(appSchema)) {
+    let jsonSchemaType = 'string';
+    if (value.type === 'number') jsonSchemaType = 'number';
+    if (value.type === 'boolean') jsonSchemaType = 'boolean';
+    
+    attributeProperties[key] = { type: jsonSchemaType };
+    if (value.format) attributeProperties[key].format = value.format;
+    if (value.required) requiredAttributes.push(key);
+  }
+  
+  // --- Build Relationship Properties ---
+  const relationshipProperties = {};
+  for (const [key, value] of Object.entries(relationshipsSchema)) {
+    const isToMany = value.type === 'hasMany';
+    relationshipProperties[key] = {
+      type: 'object',
+      properties: {
+        links: linksObject,
+        data: isToMany 
+          ? { type: 'array', items: resourceIdentifierObject } 
+          : resourceIdentifierObject
+      }
+    };
+  }
+
+  // --- Define the core Resource Object schema ---
+  const resourceObject = {
+    type: 'object',
+    required: ['type', 'id'],
+    properties: {
+      id: { type: 'string' },
+      type: { type: 'string', const: scopeName },
+      attributes: {
+        type: 'object',
+        properties: attributeProperties
+      },
+      relationships: {
+        type: 'object',
+        properties: relationshipProperties
+      },
+      links: linksObject
+    }
+  };
+
+  // --- Define the full top-level JSON:API Document ---
+  const singleDocument = {
+    type: 'object',
+    properties: {
+      data: resourceObject,
+      included: { type: 'array', items: { type: 'object' } }, // Generic included for simplicity
+      links: linksObject,
+      meta: metaObject
+    }
+  };
+  const collectionDocument = {
+    type: 'object',
+    properties: {
+      data: { type: 'array', items: resourceObject },
+      included: { type: 'array', items: { type: 'object' } },
+      links: { ...linksObject, properties: { ...linksObject.properties, next: { type: 'string' }, prev: { type: 'string' } } },
+      meta: metaObject
+    }
+  };
+
+
+  // --- Build the final schema for each route ---
+  return {
+    post: {
+      body: {
+        type: 'object',
+        required: ['data'],
+        properties: {
+          data: {
+            type: 'object',
+            required: ['type', 'attributes'],
+            properties: {
+              type: { type: 'string', const: scopeName },
+              attributes: {
+                type: 'object',
+                required: requiredAttributes,
+                properties: attributeProperties
+              },
+              relationships: {
+                type: 'object',
+                properties: relationshipProperties
+              }
+            }
+          }
+        }
+      },
+      response: { 201: singleDocument }
+    },
+    get: {
+      response: { 200: singleDocument }
+    },
+    query: {
+      response: { 200: collectionDocument }
+    },
+    patch: {
+      body: { /* A more complex partial schema would be needed for full validation */ },
+      response: { 200: singleDocument }
+    },
+    put: {
+        body: { /* Similar to POST body */ },
+        response: { 200: singleDocument }
+    }
+  };
+}
+
+
+export const HttpFastifyPlugin = {
+  name: 'http-fastify',
+
+  install(context, api) {
+    const { pluginOptions, log } = context;
+    const httpOptions = pluginOptions.http || {};
+    const { app, prefix = '/api' } = httpOptions;
+
+    if (!app) {
+      throw new HookedApiError(
+        "The 'http-fastify' plugin requires a Fastify 'app' instance to be passed in the options. Example: api.use(HttpFastifyPlugin, { http: { app: myFastifyApp } })",
+        'CONFIGURATION_ERROR'
+      );
+    }
+
+    log.info(`Fastify HTTP plugin installed. Routes will be prefixed with '${prefix}'.`);
+
+    const _createFastifyHandler = (methodName) => {
+      return async (request, reply) => {
+        const { scopeName, id } = request.params;
+        const apiParams = {
+          id,
+          inputRecord: request.body,
+          queryParams: request.query,
+        };
+        log.debug(`Fastify request for ${scopeName}.${methodName}`, { id, query: apiParams.queryParams });
+        const result = await api.scopes[scopeName][methodName](apiParams);
+        switch (methodName) {
+          case 'post':
+            reply.code(201).send(result);
+            break;
+          case 'delete':
+            reply.code(204).send();
+            break;
+          default:
+            reply.code(200).send(result);
+        }
+      };
+    };
+
+    const _createScopePlugin = (scopeName, scopeOptions) => {
+      const fastifySchema = scopeOptions.fastifySchema || _generateFastifySchema(scopeName, scopeOptions);
+
+      return async (fastifyInstance) => {
+        log.info(`Creating Fastify HTTP routes for scope: '${scopeName}'`);
+        fastifyInstance.get(`/${scopeName}`, { schema: fastifySchema.query }, _createFastifyHandler('query'));
+        fastifyInstance.get(`/${scopeName}/:id`, { schema: fastifySchema.get }, _createFastifyHandler('get'));
+        fastifyInstance.post(`/${scopeName}`, { schema: fastifySchema.post }, _createFastifyHandler('post'));
+        fastifyInstance.put(`/${scopeName}/:id`, { schema: fastifySchema.put }, _createFastifyHandler('put'));
+        fastifyInstance.patch(`/${scopeName}/:id`, { schema: fastifySchema.patch }, _createFastifyHandler('patch'));
+        fastifyInstance.delete(`/${scopeName}/:id`, { schema: fastifySchema.delete }, _createFastifyHandler('delete'));
+      };
+    };
+
+    const originalAddScope = api.addScope;
+
+    api.addScope = (name, options, extras) => {
+      const result = originalAddScope.call(api, name, options, extras);
+      app.register(_createScopePlugin(name, options), { prefix });
+      return result;
+    };
+    
+    app.setErrorHandler((error, request, reply) => {
+        handleFastifyApiError(error, request, reply, log);
+    });
+  }
+};

package/connectors_ideas/http-plugin.js

@@ -0,0 +1,138 @@
+/**
+ * http-plugin.js
+ * * This plugin for Hooked API provides a lightweight HTTP layer using Node.js's native `http` module.
+ * It creates a server and automatically generates JSON:API compliant RESTful routes for each scope.
+ *
+ * It uses the 'qs' library to parse complex query strings, just like Express.
+ * You'll need to install it: npm install qs
+ */
+import http from 'http';
+import qs from 'qs'; // The same query string parser Express uses
+import { HookedApiError } from './hooked-api.js';
+import { handleApiError } from './error-handler.js';
+
+/**
+ * A helper function to parse the JSON body from an incoming request.
+ * @param {http.IncomingMessage} req - The request object.
+ * @returns {Promise<object|null>} A promise that resolves with the parsed JSON object or null.
+ */
+async function parseJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    if (req.method !== 'POST' && req.method !== 'PUT' && req.method !== 'PATCH') {
+      return resolve(null);
+    }
+
+    let body = '';
+    req.on('data', chunk => {
+      body += chunk.toString();
+    });
+    req.on('end', () => {
+      try {
+        resolve(body ? JSON.parse(body) : null);
+      } catch (error) {
+        reject(new HookedApiError('Invalid JSON in request body.', 'BAD_REQUEST'));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+export const HttpPlugin = {
+  name: 'http',
+
+  install(context, api) {
+    const { pluginOptions, log } = context;
+    const httpOptions = pluginOptions.http || {};
+    const { port = 3000, prefix = '/api' } = httpOptions;
+
+    // This map will store our route handlers
+    const routes = new Map();
+
+    // A simple regex to match our API routes
+    // It captures the scope name and an optional ID
+    const routeRegex = new RegExp(`^${prefix}/([a-zA-Z0-9_-]+)(?:/([a-zA-Z0-9_-]+))?/?$`);
+
+    /**
+     * The main request handler for the http.Server.
+     * This function acts as our router.
+     */
+    const requestListener = async (req, res) => {
+      const { url, method } = req;
+      const [path, queryString] = url.split('?');
+
+      const match = path.match(routeRegex);
+
+      if (!match) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        return res.end(JSON.stringify({ errors: [{ status: '404', title: 'Not Found' }] }));
+      }
+
+      const [, scopeName, id] = match;
+
+      // Determine the API method based on the HTTP verb and presence of an ID
+      let apiMethodName;
+      if (method === 'GET') {
+        apiMethodName = id ? 'get' : 'query';
+      } else if (method === 'POST' && !id) {
+        apiMethodName = 'post';
+      } else if (method === 'PUT' && id) {
+        apiMethodName = 'put';
+      } else if (method === 'PATCH' && id) {
+        apiMethodName = 'patch';
+      } else if (method === 'DELETE' && id) {
+        apiMethodName = 'delete';
+      }
+
+      if (!apiMethodName || !api.scopes[scopeName]) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        return res.end(JSON.stringify({ errors: [{ status: '404', title: 'Not Found' }] }));
+      }
+
+      try {
+        // 1. Translate the native request into API method params
+        const apiParams = {};
+        
+        // Use 'qs' to parse the query string into a nested object
+        apiParams.queryParams = queryString ? qs.parse(queryString) : {};
+        apiParams.inputRecord = await parseJsonBody(req);
+        if (id) {
+          apiParams.id = id;
+        }
+
+        log.debug(`HTTP request for ${scopeName}.${apiMethodName}`, { id, query: apiParams.queryParams });
+
+        // 2. Execute the corresponding API method
+        const result = await api.scopes[scopeName][apiMethodName](apiParams);
+
+        // 3. Send the successful HTTP response
+        let statusCode = 200;
+        let responseBody = JSON.stringify(result);
+        
+        if (apiMethodName === 'post') {
+            statusCode = 201;
+        } else if (apiMethodName === 'delete') {
+            statusCode = 204;
+            responseBody = null;
+        }
+
+        res.setHeader('Content-Type', 'application/json');
+        res.writeHead(statusCode);
+        res.end(responseBody);
+
+      } catch (error) {
+        // 4. Handle any errors thrown by the API
+        // Note: The error handler now needs the `res` object directly
+        handleApiError(error, res, log);
+      }
+    };
+
+    // Create and start the HTTP server
+    const server = http.createServer(requestListener);
+    server.listen(port, () => {
+      log.info(`HTTP server started on http://localhost:${port}`);
+    });
+
+    // We no longer need to wrap addScope, as the router is dynamic.
+    // The plugin's job is simply to start the server.
+  }
+};