@bobbykim/manguito-cms-api 0.1.0 → 0.2.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bobby Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -1,7 +1,19 @@
-import { StorageAdapter, SchemaRegistry, ResolvedRateLimitConfig, CorsConfig, ServerAdapter, APIAdapter } from '@bobbykim/manguito-cms-core';
+import { ProgrammaticFieldDefinition, SchemaRegistry, StorageAdapter, ResolvedRateLimitConfig, CorsConfig, ServerAdapter, APIAdapter } from '@bobbykim/manguito-cms-core';
 import { Hono } from 'hono';
 import { DrizzlePostgresInstance } from '@bobbykim/manguito-cms-db';
 
+type ResolverMap = Map<string, ProgrammaticFieldDefinition>;
+declare function resolverKey(schema: string, field: string): string;
+declare function validateResolverBindings(registry: SchemaRegistry, resolvers: ResolverMap): void;
+declare function createProgrammaticResolver(resolvers: ResolverMap, options?: {
+    onError?: (message: string) => void;
+}): {
+    resolveItem: (schema: string, row: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    resolveList: (schema: string, rows: Record<string, unknown>[]) => Promise<Record<string, unknown>[]>;
+    hasSchema: (schema: string) => boolean;
+};
+type ProgrammaticResolver = ReturnType<typeof createProgrammaticResolver>;
+
 type CreateCmsAppOptions = {
     /** CMS display name shown in GET /admin/api/config. Defaults to 'Manguito CMS'. */
     name?: string;
@@ -15,6 +27,8 @@ type CreateCmsAppOptions = {
     };
     rateLimit?: ResolvedRateLimitConfig;
     cors?: CorsConfig;
+    /** Programmatic field resolvers, keyed `${schema}::${field}`. */
+    resolvers?: ResolverMap;
 };
 interface ManguitoCmsAPIAdapter {
     readonly prefix: string;
@@ -38,4 +52,4 @@ type APIAdapterOptions = {
 };
 declare function createAPIAdapter(options?: APIAdapterOptions): APIAdapter;
 
-export { type APIAdapterOptions, type CreateCmsAppOptions, type NodeServerOptions, createAPIAdapter, createCmsApp, createServer };
+export { type APIAdapterOptions, type CreateCmsAppOptions, type NodeServerOptions, type ProgrammaticResolver, type ResolverMap, createAPIAdapter, createCmsApp, createProgrammaticResolver, createServer, resolverKey, validateResolverBindings };

package/dist/index.d.ts

@@ -1,7 +1,19 @@
-import { StorageAdapter, SchemaRegistry, ResolvedRateLimitConfig, CorsConfig, ServerAdapter, APIAdapter } from '@bobbykim/manguito-cms-core';
+import { ProgrammaticFieldDefinition, SchemaRegistry, StorageAdapter, ResolvedRateLimitConfig, CorsConfig, ServerAdapter, APIAdapter } from '@bobbykim/manguito-cms-core';
 import { Hono } from 'hono';
 import { DrizzlePostgresInstance } from '@bobbykim/manguito-cms-db';
 
+type ResolverMap = Map<string, ProgrammaticFieldDefinition>;
+declare function resolverKey(schema: string, field: string): string;
+declare function validateResolverBindings(registry: SchemaRegistry, resolvers: ResolverMap): void;
+declare function createProgrammaticResolver(resolvers: ResolverMap, options?: {
+    onError?: (message: string) => void;
+}): {
+    resolveItem: (schema: string, row: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    resolveList: (schema: string, rows: Record<string, unknown>[]) => Promise<Record<string, unknown>[]>;
+    hasSchema: (schema: string) => boolean;
+};
+type ProgrammaticResolver = ReturnType<typeof createProgrammaticResolver>;
+
 type CreateCmsAppOptions = {
     /** CMS display name shown in GET /admin/api/config. Defaults to 'Manguito CMS'. */
     name?: string;
@@ -15,6 +27,8 @@ type CreateCmsAppOptions = {
     };
     rateLimit?: ResolvedRateLimitConfig;
     cors?: CorsConfig;
+    /** Programmatic field resolvers, keyed `${schema}::${field}`. */
+    resolvers?: ResolverMap;
 };
 interface ManguitoCmsAPIAdapter {
     readonly prefix: string;
@@ -38,4 +52,4 @@ type APIAdapterOptions = {
 };
 declare function createAPIAdapter(options?: APIAdapterOptions): APIAdapter;
 
-export { type APIAdapterOptions, type CreateCmsAppOptions, type NodeServerOptions, createAPIAdapter, createCmsApp, createServer };
+export { type APIAdapterOptions, type CreateCmsAppOptions, type NodeServerOptions, type ProgrammaticResolver, type ResolverMap, createAPIAdapter, createCmsApp, createProgrammaticResolver, createServer, resolverKey, validateResolverBindings };

package/dist/index.js

@@ -32,7 +32,10 @@ var index_exports = {};
 __export(index_exports, {
   createAPIAdapter: () => createAPIAdapter,
   createCmsApp: () => createCmsApp,
-  createServer: () => createServer
+  createProgrammaticResolver: () => createProgrammaticResolver,
+  createServer: () => createServer,
+  resolverKey: () => resolverKey,
+  validateResolverBindings: () => validateResolverBindings
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -463,6 +466,140 @@ function buildRolesRegistry(roles) {
   return Object.fromEntries(roles.map((r) => [r.name, r]));
 }
 
+// src/programmatic/resolve.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+var LIST_CONCURRENCY = 10;
+function resolverKey(schema, field) {
+  return `${schema}::${field}`;
+}
+function validateResolverBindings(registry, resolvers) {
+  const declared = /* @__PURE__ */ new Set();
+  const schemas = [
+    ...Object.values(registry.content_types),
+    ...Object.values(registry.taxonomy_types)
+  ];
+  for (const schema of schemas) {
+    for (const field of schema.fields) {
+      if (field.field_type === "programmatic") {
+        declared.add(resolverKey(schema.name, field.name));
+      }
+    }
+  }
+  const missing = [];
+  for (const key of declared) if (!resolvers.has(key)) missing.push(key);
+  const orphans = [];
+  for (const key of resolvers.keys()) if (!declared.has(key)) orphans.push(key);
+  if (missing.length === 0 && orphans.length === 0) return;
+  const lines = ["\u2717 Programmatic field resolver bindings are invalid."];
+  if (missing.length > 0) {
+    lines.push("", '  Declared as `type: "programmatic"` but no resolver found:');
+    for (const k of missing) lines.push(`    - ${k}  (add a programmaticField in src/programmatic)`);
+  }
+  if (orphans.length > 0) {
+    lines.push("", "  Resolver has no matching programmatic field in the schema:");
+    for (const k of orphans) lines.push(`    - ${k}`);
+  }
+  lines.push("", "Exiting.");
+  throw new Error(lines.join("\n"));
+}
+function buildContext(row) {
+  return {
+    get: (name) => row[name],
+    record: row
+  };
+}
+async function withTimeout(p, ms) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error("resolver timeout")), ms);
+  });
+  try {
+    return await Promise.race([p, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function runOne(def, row, onError) {
+  const fallback = def.fallback ?? null;
+  try {
+    const result = await withTimeout(
+      Promise.resolve(def.resolve(buildContext(row))),
+      def.timeout ?? DEFAULT_TIMEOUT_MS
+    );
+    return { value: result === void 0 ? null : result, failed: false };
+  } catch (err) {
+    onError(
+      `\u26A0 programmatic field ${resolverKey(def.schema, def.field)} failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return { value: fallback, failed: true };
+  }
+}
+async function runPool(items, limit, fn) {
+  let i = 0;
+  async function worker() {
+    while (i < items.length) {
+      const idx = i++;
+      await fn(items[idx]);
+    }
+  }
+  const workers = Array.from({ length: Math.min(limit, items.length) }, worker);
+  await Promise.all(workers);
+}
+function createProgrammaticResolver(resolvers, options) {
+  const onError = options?.onError ?? ((message) => {
+    process.stderr.write(message + "\n");
+  });
+  const bySchema = /* @__PURE__ */ new Map();
+  for (const def of resolvers.values()) {
+    const arr = bySchema.get(def.schema) ?? [];
+    arr.push(def);
+    bySchema.set(def.schema, arr);
+  }
+  const cache = /* @__PURE__ */ new Map();
+  async function resolveField(def, row) {
+    const itemId = row["id"] !== void 0 ? String(row["id"]) : "";
+    if (def.cache && itemId) {
+      const key = `${resolverKey(def.schema, def.field)}::${itemId}`;
+      const now = Date.now();
+      const hit = cache.get(key);
+      if (hit && hit.expires > now) return hit.value;
+      const { value: value2, failed } = await runOne(def, row, onError);
+      if (!failed) cache.set(key, { value: value2, expires: now + def.cache.ttl * 1e3 });
+      return value2;
+    }
+    const { value } = await runOne(def, row, onError);
+    return value;
+  }
+  async function resolveItem(schema, row) {
+    const defs = bySchema.get(schema);
+    if (!defs || defs.length === 0) return { ...row };
+    const out = { ...row };
+    await Promise.all(
+      defs.map(async (def) => {
+        out[def.field] = await resolveField(def, row);
+      })
+    );
+    return out;
+  }
+  async function resolveList(schema, rows) {
+    const defs = (bySchema.get(schema) ?? []).filter((d) => d.on_list === true);
+    if (defs.length === 0) return rows.map((r) => ({ ...r }));
+    const out = rows.map((r) => ({ ...r }));
+    const tasks = [];
+    for (let i = 0; i < rows.length; i++) {
+      for (const def of defs) tasks.push({ rowIndex: i, def });
+    }
+    await runPool(tasks, LIST_CONCURRENCY, async ({ rowIndex, def }) => {
+      out[rowIndex][def.field] = await resolveField(def, rows[rowIndex]);
+    });
+    return out;
+  }
+  function hasSchema(schema) {
+    return bySchema.has(schema);
+  }
+  return { resolveItem, resolveList, hasSchema };
+}
+
 // src/routes/query-params.ts
 var SORTABLE_FIELDS = /* @__PURE__ */ new Set(["title", "created_at", "updated_at"]);
 var RELATION_FIELD_TYPES = /* @__PURE__ */ new Set([
@@ -514,7 +651,7 @@ function parseFilters(url, validFields) {
 function isPublished(item) {
   return item["published"] === true;
 }
-function registerPublicContentRoutes(app, registry, repos, listRateLimit) {
+function registerPublicContentRoutes(app, registry, repos, listRateLimit, resolver) {
   function registerListRoute(path, handler) {
     if (listRateLimit) {
       app.get(path, listRateLimit, handler);
@@ -541,13 +678,13 @@ function registerPublicContentRoutes(app, registry, repos, listRateLimit) {
     const basePath = contentType.default_base_path;
     const repo = repos[typeName];
     if (!repo) continue;
-    const schemaFieldNames = /* @__PURE__ */ new Set([
-      ...contentType.fields.map((f) => f.name),
-      ...contentType.system_fields.map((f) => f.name)
-    ]);
     const relationFieldNames = new Set(
       contentType.fields.filter((f) => RELATION_FIELD_TYPES.has(f.field_type)).map((f) => f.name)
     );
+    const filterableFieldNames = /* @__PURE__ */ new Set([
+      ...contentType.fields.filter((f) => f.field_type !== "programmatic").map((f) => f.name),
+      ...contentType.system_fields.map((f) => f.name)
+    ]);
     if (contentType.only_one) {
       app.get(`/api/${basePath}`, async (c) => {
         const result = await repo.findMany({ published_only: true, page: 1, per_page: 1 });
@@ -557,7 +694,9 @@ function registerPublicContentRoutes(app, registry, repos, listRateLimit) {
             404
           );
         }
-        return c.json({ ok: true, data: result.data[0] });
+        let data = result.data[0];
+        if (resolver?.hasSchema(typeName)) data = await resolver.resolveItem(typeName, data);
+        return c.json({ ok: true, data });
       });
     } else {
       registerListRoute(`/api/${basePath}`, async (c) => {
@@ -600,7 +739,7 @@ function registerPublicContentRoutes(app, registry, repos, listRateLimit) {
             400
           );
         }
-        const filtersResult = parseFilters(c.req.url, schemaFieldNames);
+        const filtersResult = parseFilters(c.req.url, filterableFieldNames);
         if (!filtersResult.ok) {
           return c.json(
             {
@@ -637,6 +776,10 @@ function registerPublicContentRoutes(app, registry, repos, listRateLimit) {
           filters: filtersResult.filters,
           include
         });
+        if (resolver?.hasSchema(typeName)) {
+          const resolved = await resolver.resolveList(typeName, result.data);
+          return c.json({ ...result, data: resolved });
+        }
         return c.json(result);
       });
       app.get(`/api/${basePath}/:slug`, async (c) => {
@@ -666,7 +809,9 @@ function registerPublicContentRoutes(app, registry, repos, listRateLimit) {
             404
           );
         }
-        return c.json({ ok: true, data: item });
+        let data = item;
+        if (resolver?.hasSchema(typeName)) data = await resolver.resolveItem(typeName, data);
+        return c.json({ ok: true, data });
       });
     }
   }
@@ -692,6 +837,10 @@ function registerPublicContentRoutes(app, registry, repos, listRateLimit) {
         page: pagination.page,
         per_page: pagination.per_page
       });
+      if (resolver?.hasSchema(typeName)) {
+        const resolved = await resolver.resolveList(typeName, result.data);
+        return c.json({ ...result, data: resolved });
+      }
       return c.json(result);
     });
     app.get(`/api/taxonomy/${typeName}/:id`, async (c) => {
@@ -706,7 +855,9 @@ function registerPublicContentRoutes(app, registry, repos, listRateLimit) {
           404
         );
       }
-      return c.json({ ok: true, data: item });
+      let data = item;
+      if (resolver?.hasSchema(typeName)) data = await resolver.resolveItem(typeName, data);
+      return c.json({ ok: true, data });
     });
   }
 }
@@ -2662,7 +2813,7 @@ function registerUserRoutes(app, db, requirePermission, requireHierarchy) {
 var import_drizzle_orm6 = require("drizzle-orm");
 var API_VERSION = (() => {
   try {
-    return "0.1.0";
+    return "0.2.0";
   } catch {
     return "0.0.0";
   }
@@ -3078,6 +3229,9 @@ function createCmsApp(options) {
   const cmsName = options.name ?? "Manguito CMS";
   const maxFileSize = media?.max_file_size;
   const rolesRegistry = buildRolesRegistry(registry.roles.roles);
+  const resolverMap = options.resolvers ?? /* @__PURE__ */ new Map();
+  validateResolverBindings(registry, resolverMap);
+  const programmaticResolver = createProgrammaticResolver(resolverMap);
   const app = new import_hono.Hono();
   const uploadOrigins = storage.getUploadOrigins?.() ?? [];
   app.use("*", createSecurityHeadersMiddleware({ connectSrc: uploadOrigins }));
@@ -3162,7 +3316,7 @@ function createCmsApp(options) {
       paths: {}
     })
   );
-  registerPublicContentRoutes(app, registry, publicRepos, listRateLimit);
+  registerPublicContentRoutes(app, registry, publicRepos, listRateLimit, programmaticResolver);
   registerPublicMediaRoutes(app, mediaRepo, listRateLimit);
   registerConfigRoute(
     app,
@@ -3223,6 +3377,9 @@ function createAPIAdapter(options = {}) {
 0 && (module.exports = {
   createAPIAdapter,
   createCmsApp,
-  createServer
+  createProgrammaticResolver,
+  createServer,
+  resolverKey,
+  validateResolverBindings
 });
 //# sourceMappingURL=index.js.map