@flaredev/core 0.11.0 → 0.12.1

package/dist/server.js

@@ -2,9 +2,17 @@ import {
   can,
   columnName,
   createValidators,
+  enumTranslations,
   moneyExponent,
   storedFields
-} from "./chunk-62JI5DCR.js";
+} from "./chunk-BTVEH5AU.js";
+import {
+  ISSUE_CODES,
+  PROBLEM_CODES,
+  problemResponse,
+  wantsJson
+} from "./chunk-7NQIVWGG.js";
+import "./chunk-I2HSIPCF.js";
 
 // ../../node_modules/.pnpm/drizzle-orm@0.45.2_@cloudfl_21866ab18c10d2d988b916e06105fbce/node_modules/drizzle-orm/entity.js
 var entityKind = /* @__PURE__ */ Symbol.for("drizzle:entityKind");
@@ -1293,7 +1301,7 @@ function decodeCursor(raw) {
     return void 0;
   }
 }
-var TIMESTAMP_FIELDS = ["createdAt", "updatedAt"];
+var SYSTEM_SORT_FIELDS = ["id", "createdAt", "updatedAt"];
 var MAX_PER_PAGE = 100;
 var MAX_SEARCH_LENGTH = 200;
 function isSortable(def) {
@@ -1341,7 +1349,7 @@ function parseListQuery(resource, params, options = {}) {
     const direction = rawSort.startsWith("-") ? "desc" : "asc";
     const field = rawSort.replace(/^-/, "");
     const def = fields.get(field);
-    if (TIMESTAMP_FIELDS.includes(field) || def && isSortable(def)) sort = { field, direction };
+    if (SYSTEM_SORT_FIELDS.includes(field) || def && isSortable(def)) sort = { field, direction };
     else issues.push({ param: "sort", message: `can't sort by "${field}"` });
   }
   const q = params.get("q")?.trim().slice(0, MAX_SEARCH_LENGTH) || void 0;
@@ -1393,19 +1401,26 @@ function createResourceStore(options) {
     }
   }
   const keyForColumn = (name) => columns ? Object.entries(columns).find(([, column]) => column.name === name)?.[0] : ["id", "createdAt", "updatedAt", ...fields.map(([key]) => key)].find((key) => columnName(key) === name || key === name);
-  const fail = (status, error, extra = {}) => ({ ok: false, status, error, ...extra });
+  const fail = (status, error, code, issues) => ({
+    ok: false,
+    status,
+    error,
+    code,
+    ...issues?.length ? { issues } : {}
+  });
   function constraintFailure(error, action) {
     const hit = rows.constraint(error);
     if (!hit) return void 0;
     if (hit.kind === "unique") {
       const key = hit.column ? keyForColumn(hit.column) : void 0;
       const label = key ? resource.fields[key]?.label ?? key : "Value";
-      return fail(409, `${label} is already taken.`, key ? { field: key } : {});
+      const error2 = `${label} is already taken.`;
+      return fail(409, error2, PROBLEM_CODES.uniqueViolation, key ? [{ path: key, message: error2, code: ISSUE_CODES.unique }] : void 0);
     }
     if (hit.kind === "foreignKey") {
-      return action === "delete" ? fail(409, `This ${resource.label.toLowerCase()} is still referenced by other records.`) : fail(422, "A related record doesn't exist.");
+      return action === "delete" ? fail(409, `This ${resource.label.toLowerCase()} is still referenced by other records.`, PROBLEM_CODES.stillReferenced) : fail(422, "A related record doesn't exist.", PROBLEM_CODES.relatedRecordMissing);
     }
-    return fail(422, "A value is outside its allowed options.");
+    return fail(422, "A value is outside its allowed options.", PROBLEM_CODES.valueNotAllowed);
   }
   async function guarded(action, work) {
     try {
@@ -1429,8 +1444,13 @@ function createResourceStore(options) {
     await announce(action, result);
     return result;
   }
-  const invalid = (issues) => fail(422, "Validation failed.", { issues: issues.map((issue) => ({ path: issue.path.map(String).join("."), message: issue.message })) });
-  const notFound = () => fail(404, `${resource.label} not found.`);
+  const invalid = (issues) => fail(
+    422,
+    "Validation failed.",
+    PROBLEM_CODES.validationFailed,
+    issues.map((issue) => ({ path: issue.path.map(String).join("."), message: issue.message, code: ISSUE_CODES.invalid }))
+  );
+  const notFound = () => fail(404, `${resource.label} not found.`, PROBLEM_CODES.notFound);
   const computed = Object.entries(resource.computed ?? {});
   const withComputed = (row) => {
     if (computed.length === 0) return row;
@@ -1452,7 +1472,14 @@ function createResourceStore(options) {
     /** `params`: page, perPage, sort, q, filter[field], cursor (as parsed by parseListQuery). */
     async list(params, options2 = {}) {
       const parsed = parseListQuery(resource, params, options2);
-      if ("issues" in parsed) return fail(400, "Invalid query.", { queryIssues: parsed.issues });
+      if ("issues" in parsed) {
+        return fail(
+          400,
+          "Invalid query.",
+          PROBLEM_CODES.invalidQuery,
+          parsed.issues.map((issue) => ({ path: issue.param, message: issue.message, code: ISSUE_CODES.invalidParameter }))
+        );
+      }
       const { page, perPage, sort, q, filters, cursor } = parsed.query;
       const isDateField = (key) => {
         if (key === "createdAt" || key === "updatedAt") return true;
@@ -1570,14 +1597,8 @@ function createResourceStore(options) {
 }
 
 // src/server/handlers.ts
-var problem = (status, error, extra = {}) => Response.json({ error, ...extra }, { status });
-function failureResponse(failure) {
-  if (failure.queryIssues) return problem(failure.status, failure.error, { issues: failure.queryIssues });
-  const extra = {};
-  if (failure.issues) extra.issues = failure.issues;
-  if (failure.field) extra.field = failure.field;
-  return problem(failure.status, failure.error, extra);
-}
+var problem = problemResponse;
+var failureResponse = (failure) => problemResponse(failure.status, failure.error, failure.code, failure.issues);
 var respond = (result, init) => result.ok ? Response.json(result.data, init) : failureResponse(result);
 function createResourceHandlers(options) {
   const { resource, authorize } = options;
@@ -1587,13 +1608,15 @@ function createResourceHandlers(options) {
     return origin !== null && origin !== new URL(request.url).origin;
   };
   async function readBody(request) {
-    if (crossOrigin(request)) return { response: problem(403, "Cross-origin request blocked.") };
+    if (crossOrigin(request)) return { response: problem(403, "Cross-origin request blocked.", PROBLEM_CODES.crossOriginBlocked) };
     const type = request.headers.get("content-type") ?? "";
-    if (!/^application\/json\b/i.test(type)) return { response: problem(415, "Send JSON with Content-Type: application/json.") };
+    if (!/^application\/json\b/i.test(type)) {
+      return { response: problem(415, "Send JSON with Content-Type: application/json.", PROBLEM_CODES.unsupportedMediaType) };
+    }
     try {
       return { body: await request.json() };
     } catch {
-      return { response: problem(400, "Request body isn't valid JSON.") };
+      return { response: problem(400, "Request body isn't valid JSON.", PROBLEM_CODES.invalidJson) };
     }
   }
   const guard = async (context) => await authorize(context) ?? void 0;
@@ -1637,7 +1660,7 @@ function createResourceHandlers(options) {
     PATCH: (request, context) => item(request, context, "update", (id) => withBody(request, async (body) => respond(await store.update(id, body)))),
     PUT: (request, context) => item(request, context, "update", (id) => withBody(request, async (body) => respond(await store.replace(id, body)))),
     DELETE: (request, context) => item(request, context, "delete", async (id) => {
-      if (crossOrigin(request)) return problem(403, "Cross-origin request blocked.");
+      if (crossOrigin(request)) return problem(403, "Cross-origin request blocked.", PROBLEM_CODES.crossOriginBlocked);
       const result = await store.delete(id);
       return result.ok ? new Response(null, { status: 204 }) : failureResponse(result);
     })
@@ -1673,9 +1696,25 @@ function fromIndexName(name) {
   const match = /^.*?_(.+)_key$/.exec(name);
   return match ? match[1] : name;
 }
-function prismaRows(delegate, client) {
+function translate(row, enums, direction) {
+  let copy;
+  for (const key of Object.keys(enums)) {
+    const current = row[key];
+    if (typeof current !== "string") continue;
+    const mapped = enums[key][direction][current];
+    if (mapped === void 0 || mapped === current) continue;
+    copy ??= { ...row };
+    copy[key] = mapped;
+  }
+  return copy ?? row;
+}
+function prismaRows(delegate, client, resource) {
+  const enums = resource ? enumTranslations(storedFields(resource)) : {};
+  const hasEnums = Object.keys(enums).length > 0;
+  const toValue = (row) => hasEnums ? translate(row, enums, "toValue") : row;
+  const toMember = (row) => hasEnums ? translate(row, enums, "toMember") : row;
   function matching(query) {
-    const where = { ...query.filters };
+    const where = hasEnums ? { ...toMember(query.filters) } : { ...query.filters };
     if (query.search && query.search.fields.length > 0) {
       where.OR = query.search.fields.map((field) => ({ [field]: { contains: query.search.term, mode: "insensitive" } }));
     }
@@ -1688,33 +1727,37 @@ function prismaRows(delegate, client) {
       if (query.cursor) {
         const { field, id, greaterThan, isDate } = query.cursor;
         const op = greaterThan ? "gt" : "lt";
-        const value = isDate && (typeof query.cursor.value === "number" || typeof query.cursor.value === "string") ? new Date(query.cursor.value) : query.cursor.value;
+        let value = isDate && (typeof query.cursor.value === "number" || typeof query.cursor.value === "string") ? new Date(query.cursor.value) : query.cursor.value;
+        if (hasEnums && enums[field] && typeof value === "string") value = enums[field].toMember[value] ?? value;
         const keyset = [{ [field]: { [op]: value } }, { AND: [{ [field]: value }, { id: { [op]: id } }] }];
         where.AND = [...where.AND ?? [], { OR: keyset }];
       }
-      return delegate.findMany({
+      const rows = await delegate.findMany({
         where,
         orderBy: [{ [query.sort.field]: query.sort.direction }, { id: query.sort.direction }],
         take: query.limit,
         ...query.offset ? { skip: query.offset } : {}
       });
+      return hasEnums ? rows.map(toValue) : rows;
     },
     countUpTo(query, limit) {
       return delegate.count({ where: matching(query), take: limit });
     },
-    byId(id) {
-      return delegate.findUnique({ where: { id } });
+    async byId(id) {
+      const row = await delegate.findUnique({ where: { id } });
+      return row ? toValue(row) : row;
     },
     async titles(ids, titleField) {
       const rows = await delegate.findMany({ where: { id: { in: ids } }, select: { id: true, [titleField]: true } });
       return rows.map((row) => ({ id: String(row.id), title: row[titleField] }));
     },
-    insert(values) {
-      return delegate.create({ data: values });
+    async insert(values) {
+      return toValue(await delegate.create({ data: hasEnums ? toMember(values) : values }));
     },
     async update(id, values) {
       try {
-        return await delegate.update({ where: { id }, data: values });
+        const row = await delegate.update({ where: { id }, data: hasEnums ? toMember(values) : values });
+        return toValue(row);
       } catch (error) {
         if (codeOf(error) === NOT_FOUND) return null;
         throw error;
@@ -1773,6 +1816,20 @@ function fieldJsonSchema(def) {
           return { ...schema, pattern: "^#[0-9a-f]{6}$", description: "Hex colour.", examples: ["#f2541d"] };
         case "slug":
           return { ...schema, pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$", examples: ["my-first-post"] };
+        case "username":
+          return { ...schema, pattern: "^[A-Za-z0-9_][A-Za-z0-9_.]{1,31}$", description: "Username: 2\u201332 characters (letters, digits, underscore, dot).", examples: ["ada_lovelace"] };
+        case "ip":
+          return { ...schema, description: "An IPv4 or IPv6 address.", examples: ["192.168.1.1", "2001:db8::1"] };
+        case "uuid":
+          return { ...schema, format: "uuid", description: "A UUID, any version.", examples: ["123e4567-e89b-12d3-a456-426614174000"] };
+        case "timezone":
+          return { ...schema, description: "An IANA time zone identifier.", examples: ["Africa/Kampala", "America/New_York"] };
+        case "locale":
+          return { ...schema, pattern: "^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|\\d{3}))?$", description: "A BCP-47 language tag.", examples: ["en-GB", "sw-UG"] };
+        case "currency":
+          return { ...schema, pattern: "^[A-Z]{3}$", description: "ISO 4217 currency code.", examples: ["UGX", "USD"] };
+        case "postcode":
+          return { ...schema, pattern: "^[A-Za-z0-9][A-Za-z0-9 -]{0,10}[A-Za-z0-9]$", description: "Postal code.", examples: ["SW1A 1AA", "90210"] };
         default:
           return schema;
       }
@@ -1867,7 +1924,7 @@ function rolesNote(policy, action) {
 }
 function listParameters(resource) {
   const fields = storedFields(resource);
-  const sortable = ["createdAt", "updatedAt", ...fields.filter(([, def]) => isSortable(def)).map(([key]) => key)];
+  const sortable = ["id", "createdAt", "updatedAt", ...fields.filter(([, def]) => isSortable(def)).map(([key]) => key)];
   const parameters = [
     { name: "page", in: "query", schema: { type: "integer", minimum: 1, default: 1 } },
     { name: "perPage", in: "query", schema: { type: "integer", minimum: 1, maximum: 100, default: resource.perPage } },
@@ -1892,14 +1949,32 @@ function openApiDocument(options) {
   const allowed = (resource, action) => visibility === "public" || role !== null && can(policies[resource.name], role, action);
   const paths = {};
   const schemas = {
+    // One shape for every error, whatever refused the request.
     Problem: {
       type: "object",
       properties: {
-        error: { type: "string", examples: ["Validation failed."] },
-        issues: { type: "array", items: { type: "object", properties: { path: { type: "string" }, message: { type: "string" } } } },
-        field: { type: "string", description: "The field a uniqueness conflict is about." }
+        error: { type: "string", description: "The sentence to show a person. Its wording can change; do not branch on it.", examples: ["Validation failed."] },
+        code: {
+          type: "string",
+          description: "Why, as a stable value to switch on.",
+          enum: Object.values(PROBLEM_CODES),
+          examples: ["validation_failed"]
+        },
+        issues: {
+          type: "array",
+          description: "Present whenever the answer is about fields \u2014 one per failed rule, per conflicting column, or per bad query parameter.",
+          items: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Field key, dotted for a nested one, or the query parameter's name." },
+              message: { type: "string" },
+              code: { type: "string", enum: Object.values(ISSUE_CODES) }
+            },
+            required: ["path", "message"]
+          }
+        }
       },
-      required: ["error"]
+      required: ["error", "code"]
     },
     PageMeta: {
       type: "object",
@@ -2039,6 +2114,8 @@ function openApiDocument(options) {
   };
 }
 export {
+  ISSUE_CODES,
+  PROBLEM_CODES,
   createResourceHandlers,
   createResourceStore,
   drizzleRows,
@@ -2048,5 +2125,7 @@ export {
   isSortable,
   openApiDocument,
   parseListQuery,
-  prismaRows
+  prismaRows,
+  problemResponse,
+  wantsJson
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaredev/core",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Flare runtime: resource descriptors, field grammar, and Cloudflare-native helpers",
   "license": "MIT",
   "author": "Muke Johnbaptist",
@@ -56,6 +56,10 @@
       "types": "./dist/security/index.d.ts",
       "import": "./dist/security/index.js"
     },
+    "./rate-limit/server": {
+      "types": "./dist/rate-limit/server.d.ts",
+      "import": "./dist/rate-limit/server.js"
+    },
     "./security/server": {
       "types": "./dist/security/worker.d.ts",
       "import": "./dist/security/worker.js"