@objectstack/rest 1.1.0

package/dist/index.js

@@ -0,0 +1,757 @@
+// src/route-manager.ts
+var RouteManager = class {
+  constructor(server) {
+    this.server = server;
+    this.routes = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a route
+   * @param entry - Route entry with method, path, handler, and metadata
+   */
+  register(entry) {
+    if (typeof entry.handler === "string") {
+      throw new Error(
+        `String-based route handlers are not supported yet. Received handler identifier "${entry.handler}". Please provide a RouteHandler function instead.`
+      );
+    }
+    const handler = entry.handler;
+    const routeEntry = {
+      method: entry.method,
+      path: entry.path,
+      handler,
+      metadata: entry.metadata,
+      security: entry.security
+    };
+    const key = this.getRouteKey(entry.method, entry.path);
+    this.routes.set(key, routeEntry);
+    this.registerWithServer(routeEntry);
+  }
+  /**
+   * Register multiple routes
+   * @param entries - Array of route entries
+   */
+  registerMany(entries) {
+    entries.forEach((entry) => this.register(entry));
+  }
+  /**
+   * Unregister a route
+   * @param method - HTTP method
+   * @param path - Route path
+   */
+  unregister(method, path) {
+    const key = this.getRouteKey(method, path);
+    this.routes.delete(key);
+  }
+  /**
+   * Get route by method and path
+   * @param method - HTTP method
+   * @param path - Route path
+   */
+  get(method, path) {
+    const key = this.getRouteKey(method, path);
+    return this.routes.get(key);
+  }
+  /**
+   * Get all routes
+   */
+  getAll() {
+    return Array.from(this.routes.values());
+  }
+  /**
+   * Get routes by method
+   * @param method - HTTP method
+   */
+  getByMethod(method) {
+    return this.getAll().filter((route) => route.method === method);
+  }
+  /**
+   * Get routes by path prefix
+   * @param prefix - Path prefix
+   */
+  getByPrefix(prefix) {
+    return this.getAll().filter((route) => route.path.startsWith(prefix));
+  }
+  /**
+   * Get routes by tag
+   * @param tag - Tag name
+   */
+  getByTag(tag) {
+    return this.getAll().filter(
+      (route) => route.metadata?.tags?.includes(tag)
+    );
+  }
+  /**
+   * Create a route group with common prefix
+   * @param prefix - Common path prefix
+   * @param configure - Function to configure routes in the group
+   */
+  group(prefix, configure) {
+    const builder = new RouteGroupBuilder(this, prefix);
+    configure(builder);
+  }
+  /**
+   * Get route count
+   */
+  count() {
+    return this.routes.size;
+  }
+  /**
+   * Clear all routes
+   */
+  clear() {
+    this.routes.clear();
+  }
+  /**
+   * Get route key for storage
+   */
+  getRouteKey(method, path) {
+    return `${method}:${path}`;
+  }
+  /**
+   * Register route with underlying server
+   */
+  registerWithServer(entry) {
+    const { method, path, handler } = entry;
+    switch (method) {
+      case "GET":
+        this.server.get(path, handler);
+        break;
+      case "POST":
+        this.server.post(path, handler);
+        break;
+      case "PUT":
+        this.server.put(path, handler);
+        break;
+      case "DELETE":
+        this.server.delete(path, handler);
+        break;
+      case "PATCH":
+        this.server.patch(path, handler);
+        break;
+      default:
+        throw new Error(`Unsupported HTTP method: ${method}`);
+    }
+  }
+};
+var RouteGroupBuilder = class {
+  constructor(manager, prefix) {
+    this.manager = manager;
+    this.prefix = prefix;
+  }
+  /**
+   * Register GET route in group
+   */
+  get(path, handler, metadata) {
+    this.manager.register({
+      method: "GET",
+      path: this.resolvePath(path),
+      handler,
+      metadata
+    });
+    return this;
+  }
+  /**
+   * Register POST route in group
+   */
+  post(path, handler, metadata) {
+    this.manager.register({
+      method: "POST",
+      path: this.resolvePath(path),
+      handler,
+      metadata
+    });
+    return this;
+  }
+  /**
+   * Register PUT route in group
+   */
+  put(path, handler, metadata) {
+    this.manager.register({
+      method: "PUT",
+      path: this.resolvePath(path),
+      handler,
+      metadata
+    });
+    return this;
+  }
+  /**
+   * Register PATCH route in group
+   */
+  patch(path, handler, metadata) {
+    this.manager.register({
+      method: "PATCH",
+      path: this.resolvePath(path),
+      handler,
+      metadata
+    });
+    return this;
+  }
+  /**
+   * Register DELETE route in group
+   */
+  delete(path, handler, metadata) {
+    this.manager.register({
+      method: "DELETE",
+      path: this.resolvePath(path),
+      handler,
+      metadata
+    });
+    return this;
+  }
+  /**
+   * Resolve full path with prefix
+   */
+  resolvePath(path) {
+    const normalizedPrefix = this.prefix.endsWith("/") ? this.prefix.slice(0, -1) : this.prefix;
+    const normalizedPath = path.startsWith("/") ? path : "/" + path;
+    return normalizedPrefix + normalizedPath;
+  }
+};
+
+// src/rest-server.ts
+var RestServer = class {
+  constructor(server, protocol, config = {}) {
+    this.protocol = protocol;
+    this.config = this.normalizeConfig(config);
+    this.routeManager = new RouteManager(server);
+  }
+  /**
+   * Normalize configuration with defaults
+   */
+  normalizeConfig(config) {
+    const api = config.api ?? {};
+    const crud = config.crud ?? {};
+    const metadata = config.metadata ?? {};
+    const batch = config.batch ?? {};
+    const routes = config.routes ?? {};
+    return {
+      api: {
+        version: api.version ?? "v1",
+        basePath: api.basePath ?? "/api",
+        apiPath: api.apiPath,
+        enableCrud: api.enableCrud ?? true,
+        enableMetadata: api.enableMetadata ?? true,
+        enableUi: api.enableUi ?? true,
+        enableBatch: api.enableBatch ?? true,
+        enableDiscovery: api.enableDiscovery ?? true,
+        documentation: api.documentation,
+        responseFormat: api.responseFormat
+      },
+      crud: {
+        operations: crud.operations ?? {
+          create: true,
+          read: true,
+          update: true,
+          delete: true,
+          list: true
+        },
+        patterns: crud.patterns,
+        dataPrefix: crud.dataPrefix ?? "/data",
+        objectParamStyle: crud.objectParamStyle ?? "path"
+      },
+      metadata: {
+        prefix: metadata.prefix ?? "/meta",
+        enableCache: metadata.enableCache ?? true,
+        cacheTtl: metadata.cacheTtl ?? 3600,
+        endpoints: metadata.endpoints ?? {
+          types: true,
+          items: true,
+          item: true,
+          schema: true
+        }
+      },
+      batch: {
+        maxBatchSize: batch.maxBatchSize ?? 200,
+        enableBatchEndpoint: batch.enableBatchEndpoint ?? true,
+        operations: batch.operations ?? {
+          createMany: true,
+          updateMany: true,
+          deleteMany: true,
+          upsertMany: true
+        },
+        defaultAtomic: batch.defaultAtomic ?? true
+      },
+      routes: {
+        includeObjects: routes.includeObjects,
+        excludeObjects: routes.excludeObjects,
+        nameTransform: routes.nameTransform ?? "none",
+        overrides: routes.overrides
+      }
+    };
+  }
+  /**
+   * Get the full API base path
+   */
+  getApiBasePath() {
+    const { api } = this.config;
+    return api.apiPath ?? `${api.basePath}/${api.version}`;
+  }
+  /**
+   * Register all REST API routes
+   */
+  registerRoutes() {
+    const basePath = this.getApiBasePath();
+    if (this.config.api.enableDiscovery) {
+      this.registerDiscoveryEndpoints(basePath);
+    }
+    if (this.config.api.enableMetadata) {
+      this.registerMetadataEndpoints(basePath);
+    }
+    if (this.config.api.enableUi) {
+      this.registerUiEndpoints(basePath);
+    }
+    if (this.config.api.enableCrud) {
+      this.registerCrudEndpoints(basePath);
+    }
+    if (this.config.api.enableBatch) {
+      this.registerBatchEndpoints(basePath);
+    }
+  }
+  /**
+   * Register discovery endpoints
+   */
+  registerDiscoveryEndpoints(basePath) {
+    this.routeManager.register({
+      method: "GET",
+      path: basePath,
+      handler: async (_req, res) => {
+        try {
+          const discovery = await this.protocol.getDiscovery();
+          discovery.version = this.config.api.version;
+          if (discovery.endpoints) {
+            if (this.config.api.enableCrud) {
+              discovery.endpoints.data = `${basePath}${this.config.crud.dataPrefix}`;
+            }
+            if (this.config.api.enableMetadata) {
+              discovery.endpoints.metadata = `${basePath}${this.config.metadata.prefix}`;
+            }
+            if (this.config.api.enableUi) {
+              discovery.endpoints.ui = `${basePath}/ui`;
+            }
+            if (discovery.endpoints.auth) {
+              discovery.endpoints.auth = `${basePath}/auth`;
+            }
+          }
+          res.json(discovery);
+        } catch (error) {
+          res.status(500).json({ error: error.message });
+        }
+      },
+      metadata: {
+        summary: "Get API discovery information",
+        tags: ["discovery"]
+      }
+    });
+  }
+  /**
+   * Register metadata endpoints
+   */
+  registerMetadataEndpoints(basePath) {
+    const { metadata } = this.config;
+    const metaPath = `${basePath}${metadata.prefix}`;
+    if (metadata.endpoints.types !== false) {
+      this.routeManager.register({
+        method: "GET",
+        path: metaPath,
+        handler: async (_req, res) => {
+          try {
+            const types = await this.protocol.getMetaTypes();
+            res.json(types);
+          } catch (error) {
+            res.status(500).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "List all metadata types",
+          tags: ["metadata"]
+        }
+      });
+    }
+    if (metadata.endpoints.items !== false) {
+      this.routeManager.register({
+        method: "GET",
+        path: `${metaPath}/:type`,
+        handler: async (req, res) => {
+          try {
+            const items = await this.protocol.getMetaItems({ type: req.params.type });
+            res.json(items);
+          } catch (error) {
+            res.status(404).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "List metadata items of a type",
+          tags: ["metadata"]
+        }
+      });
+    }
+    if (metadata.endpoints.item !== false) {
+      this.routeManager.register({
+        method: "GET",
+        path: `${metaPath}/:type/:name`,
+        handler: async (req, res) => {
+          try {
+            if (metadata.enableCache && this.protocol.getMetaItemCached) {
+              const cacheRequest = {
+                ifNoneMatch: req.headers["if-none-match"],
+                ifModifiedSince: req.headers["if-modified-since"]
+              };
+              const result = await this.protocol.getMetaItemCached({
+                type: req.params.type,
+                name: req.params.name,
+                cacheRequest
+              });
+              if (result.notModified) {
+                res.status(304).send();
+                return;
+              }
+              if (result.etag) {
+                const etagValue = result.etag.weak ? `W/"${result.etag.value}"` : `"${result.etag.value}"`;
+                res.header("ETag", etagValue);
+              }
+              if (result.lastModified) {
+                res.header("Last-Modified", new Date(result.lastModified).toUTCString());
+              }
+              if (result.cacheControl) {
+                const directives = result.cacheControl.directives.join(", ");
+                const maxAge = result.cacheControl.maxAge ? `, max-age=${result.cacheControl.maxAge}` : "";
+                res.header("Cache-Control", directives + maxAge);
+              }
+              res.json(result.data);
+            } else {
+              const item = await this.protocol.getMetaItem({ type: req.params.type, name: req.params.name });
+              res.json(item);
+            }
+          } catch (error) {
+            res.status(404).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Get specific metadata item",
+          tags: ["metadata"]
+        }
+      });
+    }
+    this.routeManager.register({
+      method: "PUT",
+      path: `${metaPath}/:type/:name`,
+      handler: async (req, res) => {
+        try {
+          if (!this.protocol.saveMetaItem) {
+            res.status(501).json({ error: "Save operation not supported by protocol implementation" });
+            return;
+          }
+          const result = await this.protocol.saveMetaItem({
+            type: req.params.type,
+            name: req.params.name,
+            item: req.body
+          });
+          res.json(result);
+        } catch (error) {
+          res.status(400).json({ error: error.message });
+        }
+      },
+      metadata: {
+        summary: "Save specific metadata item",
+        tags: ["metadata"]
+      }
+    });
+  }
+  /**
+   * Register UI endpoints
+   */
+  registerUiEndpoints(basePath) {
+    const uiPath = `${basePath}/ui`;
+    this.routeManager.register({
+      method: "GET",
+      path: `${uiPath}/view/:object/:type`,
+      handler: async (req, res) => {
+        try {
+          if (this.protocol.getUiView) {
+            const view = await this.protocol.getUiView({
+              object: req.params.object,
+              type: req.params.type
+            });
+            res.json(view);
+          } else {
+            res.status(501).json({ error: "UI View resolution not supported by protocol implementation" });
+          }
+        } catch (error) {
+          res.status(404).json({ error: error.message });
+        }
+      },
+      metadata: {
+        summary: "Resolve UI View for object",
+        tags: ["ui"]
+      }
+    });
+  }
+  /**
+   * Register CRUD endpoints for data operations
+   */
+  registerCrudEndpoints(basePath) {
+    const { crud } = this.config;
+    const dataPath = `${basePath}${crud.dataPrefix}`;
+    const operations = crud.operations;
+    if (operations.list) {
+      this.routeManager.register({
+        method: "GET",
+        path: `${dataPath}/:object`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.findData({
+              object: req.params.object,
+              query: req.query
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Query records",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+    if (operations.read) {
+      this.routeManager.register({
+        method: "GET",
+        path: `${dataPath}/:object/:id`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.getData({
+              object: req.params.object,
+              id: req.params.id
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(404).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Get record by ID",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+    if (operations.create) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.createData({
+              object: req.params.object,
+              data: req.body
+            });
+            res.status(201).json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Create record",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+    if (operations.update) {
+      this.routeManager.register({
+        method: "PATCH",
+        path: `${dataPath}/:object/:id`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.updateData({
+              object: req.params.object,
+              id: req.params.id,
+              data: req.body
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Update record",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+    if (operations.delete) {
+      this.routeManager.register({
+        method: "DELETE",
+        path: `${dataPath}/:object/:id`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.deleteData({
+              object: req.params.object,
+              id: req.params.id
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Delete record",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+  }
+  /**
+   * Register batch operation endpoints
+   */
+  registerBatchEndpoints(basePath) {
+    const { crud, batch } = this.config;
+    const dataPath = `${basePath}${crud.dataPrefix}`;
+    const operations = batch.operations;
+    if (batch.enableBatchEndpoint && this.protocol.batchData) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object/batch`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.batchData({
+              object: req.params.object,
+              request: req.body
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Batch operations",
+          tags: ["data", "batch"]
+        }
+      });
+    }
+    if (operations.createMany && this.protocol.createManyData) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object/createMany`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.createManyData({
+              object: req.params.object,
+              records: req.body || []
+            });
+            res.status(201).json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Create multiple records",
+          tags: ["data", "batch"]
+        }
+      });
+    }
+    if (operations.updateMany && this.protocol.updateManyData) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object/updateMany`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.updateManyData({
+              object: req.params.object,
+              ...req.body
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Update multiple records",
+          tags: ["data", "batch"]
+        }
+      });
+    }
+    if (operations.deleteMany && this.protocol.deleteManyData) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object/deleteMany`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.deleteManyData({
+              object: req.params.object,
+              ...req.body
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Delete multiple records",
+          tags: ["data", "batch"]
+        }
+      });
+    }
+  }
+  /**
+   * Get the route manager
+   */
+  getRouteManager() {
+    return this.routeManager;
+  }
+  /**
+   * Get all registered routes
+   */
+  getRoutes() {
+    return this.routeManager.getAll();
+  }
+};
+
+// src/rest-api-plugin.ts
+function createRestApiPlugin(config = {}) {
+  return {
+    name: "com.objectstack.rest.api",
+    version: "1.0.0",
+    init: async (_ctx) => {
+    },
+    start: async (ctx) => {
+      const serverService = config.serverServiceName || "http.server";
+      const protocolService = config.protocolServiceName || "protocol";
+      let server;
+      let protocol;
+      try {
+        server = ctx.getService(serverService);
+      } catch (e) {
+      }
+      try {
+        protocol = ctx.getService(protocolService);
+      } catch (e) {
+      }
+      if (!server) {
+        ctx.logger.warn(`RestApiPlugin: HTTP Server service '${serverService}' not found. REST routes skipped.`);
+        return;
+      }
+      if (!protocol) {
+        ctx.logger.warn(`RestApiPlugin: Protocol service '${protocolService}' not found. REST routes skipped.`);
+        return;
+      }
+      ctx.logger.info("Hydrating REST API from Protocol...");
+      try {
+        const restServer = new RestServer(server, protocol, config.api);
+        restServer.registerRoutes();
+        ctx.logger.info("REST API successfully registered");
+      } catch (err) {
+        ctx.logger.error("Failed to register REST API routes", { error: err.message });
+        throw err;
+      }
+    }
+  };
+}
+var createApiRegistryPlugin = createRestApiPlugin;
+export {
+  RestServer,
+  RouteGroupBuilder,
+  RouteManager,
+  createApiRegistryPlugin,
+  createRestApiPlugin
+};
+//# sourceMappingURL=index.js.map