@flaredev/core 0.1.0

package/dist/server.js

@@ -0,0 +1,319 @@
+import {
+  createValidators,
+  storedFields
+} from "./chunk-DARDHZPX.js";
+
+// src/server/store.ts
+import { and, asc, count, desc, eq, getTableColumns, inArray, isNull, or, sql } from "drizzle-orm";
+
+// src/server/query.ts
+var TIMESTAMP_FIELDS = ["createdAt", "updatedAt"];
+var MAX_PER_PAGE = 100;
+var MAX_SEARCH_LENGTH = 200;
+function isSortable(def) {
+  return def.sortable ?? !["text", "file"].includes(def.kind);
+}
+function isFilterable(def) {
+  return def.filterable ?? ["enum", "boolean", "belongsTo"].includes(def.kind);
+}
+function isSearchable(def) {
+  return def.searchable ?? def.kind === "string";
+}
+function coerce(def, raw) {
+  if (raw === "null") return def.required ? void 0 : null;
+  switch (def.kind) {
+    case "boolean":
+      return raw === "true" || raw === "1" ? true : raw === "false" || raw === "0" ? false : void 0;
+    case "int":
+      return /^-?\d+$/.test(raw) ? Number(raw) : void 0;
+    case "float":
+      return raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : void 0;
+    case "enum":
+      return def.options.includes(raw) ? raw : void 0;
+    default:
+      return raw;
+  }
+}
+function parseListQuery(resource, params) {
+  const issues = [];
+  const fields = new Map(storedFields(resource));
+  const positiveInt = (name, fallback, max = Number.MAX_SAFE_INTEGER) => {
+    const raw = params.get(name);
+    if (raw === null) return fallback;
+    const value = Number(raw);
+    if (!/^\d+$/.test(raw) || value < 1 || value > max) {
+      issues.push({ param: name, message: `must be an integer from 1 to ${max === Number.MAX_SAFE_INTEGER ? "\u221E" : max}` });
+      return fallback;
+    }
+    return value;
+  };
+  const page = positiveInt("page", 1);
+  const perPage = positiveInt("perPage", resource.perPage, MAX_PER_PAGE);
+  let sort = resource.defaultSort;
+  const rawSort = params.get("sort");
+  if (rawSort) {
+    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 };
+    else issues.push({ param: "sort", message: `can't sort by "${field}"` });
+  }
+  const q = params.get("q")?.trim().slice(0, MAX_SEARCH_LENGTH) || void 0;
+  const filters = {};
+  for (const [name, raw] of params) {
+    const match = /^filter\[(.+)\]$/.exec(name);
+    if (!match) continue;
+    const key = match[1];
+    const def = fields.get(key);
+    if (!def || !isFilterable(def)) {
+      issues.push({ param: name, message: `can't filter by "${key}"` });
+      continue;
+    }
+    const value = coerce(def, raw);
+    if (value === void 0) issues.push({ param: name, message: `invalid value "${raw}"` });
+    else filters[key] = value;
+  }
+  return issues.length ? { issues } : { query: { page, perPage, sort, q, filters } };
+}
+
+// src/server/store.ts
+function errorText(error) {
+  const parts = [];
+  for (let current = error, depth = 0; current && depth < 5; depth++) {
+    if (current instanceof Error) {
+      parts.push(current.message);
+      current = current.cause;
+    } else {
+      parts.push(String(current));
+      break;
+    }
+  }
+  return parts.join(" | ");
+}
+function createResourceStore(options) {
+  const { resource, table, getDb } = options;
+  const validators = createValidators(resource);
+  const columns = getTableColumns(table);
+  const fields = storedFields(resource);
+  for (const key of ["id", "createdAt", "updatedAt", ...fields.map(([key2]) => key2)]) {
+    if (!columns[key]) {
+      throw new Error(`Resource "${resource.name}": table has no column for "${key}". Run \`flare sync-types\` and create a migration.`);
+    }
+  }
+  const idColumn = columns.id;
+  const columnKeyByName = new Map(Object.entries(columns).map(([key, column]) => [column.name, key]));
+  const fail = (status, error, extra = {}) => ({ ok: false, status, error, ...extra });
+  function constraintFailure(error, action) {
+    const text = errorText(error);
+    const unique = /UNIQUE constraint failed: ([\w.]+(?:, [\w.]+)*)/.exec(text);
+    if (unique) {
+      const key = columnKeyByName.get(unique[1].split(", ")[0].split(".").pop());
+      const label = key ? resource.fields[key]?.label ?? key : "Value";
+      return fail(409, `${label} is already taken.`, key ? { field: key } : {});
+    }
+    if (/FOREIGN KEY constraint failed/.test(text)) {
+      return action === "delete" ? fail(409, `This ${resource.label.toLowerCase()} is still referenced by other records.`) : fail(422, "A related record doesn't exist.");
+    }
+    if (/CHECK constraint failed/.test(text)) return fail(422, "A value is outside its allowed options.");
+    return void 0;
+  }
+  async function guarded(action, work) {
+    try {
+      return await work();
+    } catch (error) {
+      const failure = constraintFailure(error, action);
+      if (failure) return failure;
+      throw error;
+    }
+  }
+  async function announce(action, result) {
+    if (!options.onChange || !result.ok) return;
+    try {
+      await options.onChange({ resource: resource.name, action, id: String(result.data.id) });
+    } catch (error) {
+      console.error(`[flare] ${resource.name} ${action} cache invalidation failed:`, error);
+    }
+  }
+  async function writing(action, work) {
+    const result = await guarded(action, work);
+    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 byId = (id) => eq(idColumn, id);
+  const notFound = () => fail(404, `${resource.label} not found.`);
+  return {
+    resource,
+    table,
+    /** `params`: page, perPage, sort, q, filter[field] (as parsed by parseListQuery). */
+    async list(params) {
+      const parsed = parseListQuery(resource, params);
+      if ("issues" in parsed) return fail(400, "Invalid query.", { queryIssues: parsed.issues });
+      const { page, perPage, sort, q, filters } = parsed.query;
+      const conditions = [];
+      if (q) {
+        const pattern = `%${q.replace(/[\\%_]/g, (char) => `\\${char}`)}%`;
+        const searchable = fields.filter(([, def]) => isSearchable(def)).map(([key]) => columns[key]);
+        if (searchable.length) conditions.push(or(...searchable.map((column) => sql`${column} LIKE ${pattern} ESCAPE '\\'`)));
+      }
+      for (const [key, value] of Object.entries(filters)) {
+        conditions.push(value === null ? isNull(columns[key]) : eq(columns[key], value));
+      }
+      const where = conditions.length ? and(...conditions) : void 0;
+      const order = sort.direction === "asc" ? asc(columns[sort.field]) : desc(columns[sort.field]);
+      const db = getDb();
+      const [rows, totals] = await Promise.all([
+        db.select().from(table).where(where).orderBy(order, asc(idColumn)).limit(perPage).offset((page - 1) * perPage),
+        db.select({ total: count() }).from(table).where(where)
+      ]);
+      const total = totals[0]?.total ?? 0;
+      return {
+        ok: true,
+        data: { data: rows, meta: { page, perPage, total, totalPages: Math.max(1, Math.ceil(total / perPage)) } }
+      };
+    },
+    async get(id) {
+      const [record] = await getDb().select().from(table).where(byId(id)).limit(1);
+      return record ? { ok: true, data: record } : notFound();
+    },
+    /** Title-field values for a set of ids (for showing relations). Missing ids are omitted. */
+    async titles(ids) {
+      const unique = [...new Set(ids.filter(Boolean))];
+      if (unique.length === 0) return {};
+      const titleColumn = columns[resource.titleField] ?? idColumn;
+      const rows = await getDb().select({ id: idColumn, title: titleColumn }).from(table).where(inArray(idColumn, unique));
+      return Object.fromEntries(rows.map((row) => [row.id, row.title == null ? row.id : String(row.title)]));
+    },
+    create(input) {
+      const result = validators.create.safeParse(input);
+      if (!result.success) return Promise.resolve(invalid(result.error.issues));
+      return writing("create", async () => {
+        const now = /* @__PURE__ */ new Date();
+        const [record] = await getDb().insert(table).values({ ...result.data, id: crypto.randomUUID(), createdAt: now, updatedAt: now }).returning();
+        return { ok: true, data: record };
+      });
+    },
+    /** Partial update (PATCH semantics). */
+    update(id, input) {
+      const result = validators.update.safeParse(input);
+      if (!result.success) return Promise.resolve(invalid(result.error.issues));
+      return writing("update", async () => {
+        const [record] = await getDb().update(table).set({ ...result.data, updatedAt: /* @__PURE__ */ new Date() }).where(byId(id)).returning();
+        return record ? { ok: true, data: record } : notFound();
+      });
+    },
+    /** Full replacement (PUT semantics): omitted fields go back to their default, or null when optional. */
+    replace(id, input) {
+      const result = validators.create.safeParse(input);
+      if (!result.success) return Promise.resolve(invalid(result.error.issues));
+      return writing("update", async () => {
+        const values = {};
+        for (const [key, def] of fields) {
+          values[key] = "default" in def && def.default !== void 0 ? def.default : def.required ? void 0 : null;
+        }
+        Object.assign(values, result.data, { updatedAt: /* @__PURE__ */ new Date() });
+        const [record] = await getDb().update(table).set(values).where(byId(id)).returning();
+        return record ? { ok: true, data: record } : notFound();
+      });
+    },
+    delete(id) {
+      return writing("delete", async () => {
+        const deleted = await getDb().delete(table).where(byId(id)).returning({ id: idColumn });
+        return deleted.length ? { ok: true, data: { id } } : notFound();
+      });
+    }
+  };
+}
+
+// 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 respond = (result, init) => result.ok ? Response.json(result.data, init) : failureResponse(result);
+function createResourceHandlers(options) {
+  const { resource, authorize } = options;
+  const store = createResourceStore(options);
+  const crossOrigin = (request) => {
+    const origin = request.headers.get("origin");
+    return origin !== null && origin !== new URL(request.url).origin;
+  };
+  async function readBody(request) {
+    if (crossOrigin(request)) return { response: problem(403, "Cross-origin request blocked.") };
+    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.") };
+    try {
+      return { body: await request.json() };
+    } catch {
+      return { response: problem(400, "Request body isn't valid JSON.") };
+    }
+  }
+  const guard = async (context) => await authorize(context) ?? void 0;
+  async function drain(request) {
+    if (!request.body || request.bodyUsed) return;
+    try {
+      const reader = request.body.getReader();
+      while (!(await reader.read()).done) ;
+    } catch {
+    }
+  }
+  const draining = (handler) => async (request, ...rest) => {
+    const response = await handler(request, ...rest);
+    await drain(request);
+    return response;
+  };
+  async function GET(request) {
+    const denied = await guard({ request, resource, action: "list" });
+    if (denied) return denied;
+    return respond(await store.list(new URL(request.url).searchParams));
+  }
+  async function POST(request) {
+    const denied = await guard({ request, resource, action: "create" });
+    if (denied) return denied;
+    const read = await readBody(request);
+    if ("response" in read) return read.response;
+    const result = await store.create(read.body);
+    if (!result.ok) return failureResponse(result);
+    const location = `${new URL(request.url).pathname.replace(/\/$/, "")}/${result.data.id}`;
+    return Response.json(result.data, { status: 201, headers: { location } });
+  }
+  async function item(request, context, action, work) {
+    const { id } = await context.params;
+    const denied = await guard({ request, resource, action, id });
+    if (denied) return denied;
+    return work(id);
+  }
+  const withBody = (request, run) => readBody(request).then((read) => "response" in read ? read.response : run(read.body));
+  const itemHandlers = {
+    GET: (request, context) => item(request, context, "read", async (id) => respond(await store.get(id))),
+    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.");
+      const result = await store.delete(id);
+      return result.ok ? new Response(null, { status: 204 }) : failureResponse(result);
+    })
+  };
+  return {
+    collection: { GET, POST: draining(POST) },
+    item: {
+      GET: itemHandlers.GET,
+      PATCH: draining(itemHandlers.PATCH),
+      PUT: draining(itemHandlers.PUT),
+      DELETE: draining(itemHandlers.DELETE)
+    },
+    store
+  };
+}
+export {
+  createResourceHandlers,
+  createResourceStore,
+  isFilterable,
+  isSearchable,
+  isSortable,
+  parseListQuery
+};

package/dist/types-B6Y73BgH.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Wire protocol shared by the server (RealtimeChannel DO), the framework's
+ * non-React client, and the useRealtime hook.
+ *
+ * All frames are single JSON text messages. There is no binary path and no
+ * message exceeding 1 MiB. Unknown message types are ignored server-side.
+ */
+/** Arbitrary application metadata a connection can attach to its presence. */
+type RealtimePresenceData = Record<string, unknown> | null;
+/** One connected member, as announced in `hello` and `presence` frames. */
+interface RealtimeMember {
+    /** Server-assigned id for this connection (unique within the channel). */
+    connectionId: string;
+    presence: RealtimePresenceData;
+}
+/** Reconnect policy for the client, with sane server-friendly defaults. */
+interface RealtimeReconnectPolicy {
+    /**
+     * Delay before the first reconnect after a drop. Doubled on every failed
+     * attempt (with optional jitter) up to `maxDelayMs`. Reset after the socket
+     * has stayed open for `stableMs`.
+     */
+    minDelayMs?: number;
+    /** Hard cap on any single reconnect delay. */
+    maxDelayMs?: number;
+    /** Exponential multiplier: delay * factor per attempt. */
+    factor?: number;
+    /** Add up to ±jitterRatio*delay of randomness to avoid thundering herds. */
+    jitterRatio?: number;
+    /** Give up reconnecting after this many failed attempts (0 = never). */
+    maxRetries?: number;
+    /**
+     * How long to attempt reconnecting without user interaction before the hook
+     * reports `status: "dead"` instead of `"reconnecting"`.
+     */
+    deadAfterMs?: number;
+    /** Send a keepalive ping every `heartbeatMs`; force-reconnect after two intervals without a pong. */
+    heartbeatMs?: number;
+    /**
+     * How long a socket must stay open before the backoff resets. A server that
+     * accepts and immediately closes (an auth reject, a crashing DO) keeps backing
+     * off instead of reconnecting at `minDelayMs` forever.
+     */
+    stableMs?: number;
+}
+/** Client connection lifecycle, as surfaced by useRealtime and RealtimeClient. */
+type RealtimeStatus = "connecting" | "open" | "reconnecting" | "dead" | "closed";
+interface RealtimeEvent {
+    e: string;
+    d: unknown;
+    from?: string;
+}
+
+export type { RealtimePresenceData as R, RealtimeReconnectPolicy as a, RealtimeStatus as b, RealtimeMember as c, RealtimeEvent as d };

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@flaredev/core",
+  "version": "0.1.0",
+  "description": "Flare runtime: resource descriptors, field grammar, and Cloudflare-native helpers",
+  "license": "MIT",
+  "author": "Muke Johnbaptist",
+  "homepage": "https://flare-docs.codetotech.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MUKE-coder/flare-framework.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/MUKE-coder/flare-framework/issues"
+  },
+  "keywords": [
+    "cloudflare",
+    "workers",
+    "vinext",
+    "fullstack",
+    "framework",
+    "d1",
+    "drizzle",
+    "generator",
+    "admin"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./realtime": {
+      "types": "./dist/realtime/client.d.ts",
+      "import": "./dist/realtime/client.js"
+    },
+    "./realtime/server": {
+      "types": "./dist/realtime/server.d.ts",
+      "import": "./dist/realtime/server.js"
+    },
+    "./security": {
+      "types": "./dist/security/index.d.ts",
+      "import": "./dist/security/index.js"
+    },
+    "./security/server": {
+      "types": "./dist/security/worker.d.ts",
+      "import": "./dist/security/worker.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/sql.js": "^1.4.11",
+    "drizzle-orm": "^0.45.2",
+    "sql.js": "^1.14.2"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.2",
+    "react": "^18.2 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}