@flaredev/core 0.3.0 → 0.4.0

package/dist/{chunk-434JXSDV.js → chunk-PWP4QEZV.js}

@@ -152,6 +152,9 @@ function defineResource(config) {
     label: config.label ?? humanize(name),
     pluralLabel: config.pluralLabel ?? humanize(pluralName),
     icon: config.icon,
+    group: config.group,
+    hooks: config.hooks ?? {},
+    computed: config.computed ?? {},
     titleField,
     defaultSort,
     perPage,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as Field, C as CreateInput, U as UpdateInput, R as Resource, S as StoredField } from './policy-BqRg9RVM.js';
-export { B as BelongsToField, a as BooleanField, D as DEFAULT_FILE_MAX_BYTES, b as DateField, c as DateTimeField, E as EnumField, d as FILE_CATEGORIES, e as FieldKind, f as FieldValue, g as FileCategory, h as FileField, i as FloatField, H as HasManyField, I as IntField, M as MultiSelectField, P as Policy, j as PolicyAction, k as PolicyConfig, l as PolicyError, m as RESERVED_FIELD_NAMES, n as RecordOf, o as ResourceConfig, p as ResourceDefinitionError, q as STRING_FORMATS, r as StringField, s as StringFormat, T as TextField, t as allowedActions, u as can, v as columnName, w as defaultFieldLabel, x as definePolicy, y as defineResource, z as field, A as fileMaxBytes, G as mimeTypesFor, J as storedFields } from './policy-BqRg9RVM.js';
+import { F as Field, C as CreateInput, U as UpdateInput, R as Resource, S as StoredField } from './policy-CvfE-wCK.js';
+export { B as BelongsToField, a as BooleanField, D as DEFAULT_FILE_MAX_BYTES, b as DateField, c as DateTimeField, E as EnumField, d as FILE_CATEGORIES, e as FieldKind, f as FieldValue, g as FileCategory, h as FileField, i as FloatField, H as HasManyField, I as IntField, M as MultiSelectField, P as Policy, j as PolicyAction, k as PolicyConfig, l as PolicyError, m as RESERVED_FIELD_NAMES, n as RecordOf, o as ResourceConfig, p as ResourceDefinitionError, q as STRING_FORMATS, r as StringField, s as StringFormat, T as TextField, t as allowedActions, u as can, v as columnName, w as defaultFieldLabel, x as definePolicy, y as defineResource, z as field, A as fileMaxBytes, G as mimeTypesFor, J as storedFields } from './policy-CvfE-wCK.js';
 import { z } from 'zod';
 
 /**
@@ -507,6 +507,6 @@ interface SeedContext {
 type Seed = (context: SeedContext) => void | Promise<void>;
 declare function defineSeed(seed: Seed): Seed;
 
-declare const FLARE_VERSION = "0.3.0";
+declare const FLARE_VERSION = "0.4.0";
 
 export { type BelongsToRelation, type Country, CreateInput, FLARE_VERSION, type Fake, Field, type FormValues, type FormatOptions, type HasManyRelation, type InsertMany, type MailMessage, type MailResult, type Mailer, type MailerOptions, PBKDF2_ITERATIONS, type ReadUrlOptions, RelationError, type RelationGraph, Resource, type ResourceRelations, type ResourceValidators, SNIFF_BYTES, SUBSCRIPTION_STATUSES, type Seed, type SeedContext, type Storage, type StorageBucket, type StorageOptions, StoredField, type SubscriptionLike, type SubscriptionState, type SubscriptionStatus, type Tone, type TransactionalEmail, UpdateInput, type UploadUrlOptions, camelCase, checkoutPaid, countries, countryName, createFake, createMailer, createObjectKey, createStorage, createValidators, currentPeriodEnd, defineSeed, fake, fieldSchema, fileKeyPrefix, flagEmoji, formValuesToInput, formatPhone, formatValue, grantsAccess, hashPassword, humanize, importSigningKey, initialFormValues, isColor, isCountryCode, isDomain, isLiveSubscription, isPhoneNumber, isSlug, issuesByField, kebabCase, matchesContentType, normalizeDomain, optionLabel, parseMultiValue, pascalCase, pluralize, randomLetters, relationGraph, renderTransactionalEmail, shouldApplySubscription, signToken, slugify, snakeCase, sniffMatches, splitPhone, statusTone, subscriptionPriceId, subscriptionState, toE164, toSubscriptionStatus, verifyPassword, verifyToken, words };

package/dist/index.js

@@ -38,7 +38,7 @@ import {
   storedFields,
   toE164,
   words
-} from "./chunk-434JXSDV.js";
+} from "./chunk-PWP4QEZV.js";
 
 // src/password.ts
 var ALGORITHM = "pbkdf2-sha256";
@@ -962,7 +962,7 @@ function createFake(seed = 20260101) {
 var fake = createFake();
 
 // src/index.ts
-var FLARE_VERSION = "0.3.0";
+var FLARE_VERSION = "0.4.0";
 export {
   DEFAULT_FILE_MAX_BYTES,
   FILE_CATEGORIES,

package/dist/{policy-BqRg9RVM.d.ts → policy-CvfE-wCK.d.ts}

@@ -223,6 +223,11 @@ interface ResourceConfig<Fields extends Record<string, Field>> {
     pluralLabel?: string;
     /** lucide-react icon name for navigation, e.g. "users". Default: a generic document icon. */
     icon?: string;
+    /**
+     * Heading this resource sits under in the dashboard sidebar, e.g. "Sales". Resources
+     * without one share a "Resources" group, which is all a small app needs.
+     */
+    group?: string;
     /** Field used to represent a record in lists and relation pickers. Default: first string field. */
     titleField?: FieldKey<Fields>;
     defaultSort?: {
@@ -231,6 +236,49 @@ interface ResourceConfig<Fields extends Record<string, Field>> {
     };
     /** Page size for list endpoints and tables. Default 25. */
     perPage?: number;
+    /**
+     * Your logic, beside the fields it belongs to. Every write — the REST API, the
+     * dashboard's forms, a seed, an import — goes through the same store, so a hook here
+     * runs for all of them, and there's one place to read to know what happens on a write.
+     */
+    hooks?: ResourceHooks;
+    /**
+     * Values worked out from the record rather than stored: a total from a quantity and a
+     * price, a full name from two columns. They're added to every record the API and the
+     * dashboard return, and there's no column and no migration behind them.
+     */
+    computed?: Record<string, (record: Record<string, unknown>) => unknown>;
+}
+/** What a hook is handed: the request's own database and who is making it. */
+interface HookContext {
+    /** Drizzle, already bound to this request. */
+    db: any;
+    /** The signed-in user, when the write came from somewhere that has one. */
+    user?: {
+        id: string;
+        email: string;
+        role?: string | null;
+    } | null;
+}
+interface ResourceHooks {
+    /** Change or check the input before it's written. Return the input (changed or not), or throw to refuse. */
+    beforeCreate?: (input: Record<string, unknown>, context: HookContext) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    afterCreate?: (record: Record<string, unknown>, context: HookContext) => Promise<void> | void;
+    beforeUpdate?: (input: Record<string, unknown>, context: HookContext & {
+        id: string;
+        current: Record<string, unknown> | null;
+    }) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    afterUpdate?: (record: Record<string, unknown>, context: HookContext & {
+        previous: Record<string, unknown> | null;
+    }) => Promise<void> | void;
+    /** Throw to refuse the delete. */
+    beforeDelete?: (context: HookContext & {
+        id: string;
+        current: Record<string, unknown> | null;
+    }) => Promise<void> | void;
+    afterDelete?: (context: HookContext & {
+        id: string;
+    }) => Promise<void> | void;
 }
 interface Resource<Fields extends Record<string, Field> = Record<string, Field>> {
     name: string;
@@ -239,6 +287,9 @@ interface Resource<Fields extends Record<string, Field> = Record<string, Field>>
     label: string;
     pluralLabel: string;
     icon: string | undefined;
+    group: string | undefined;
+    hooks: ResourceHooks;
+    computed: Record<string, (record: Record<string, unknown>) => unknown>;
     titleField: string;
     defaultSort: {
         field: string;

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
 import { BaseSQLiteDatabase, SQLiteTable } from 'drizzle-orm/sqlite-core';
-import { S as StoredField, R as Resource, F as Field, P as Policy } from './policy-BqRg9RVM.js';
+import { S as StoredField, R as Resource, F as Field, P as Policy } from './policy-CvfE-wCK.js';
 
 interface ListQuery {
     page: number;
@@ -12,6 +12,19 @@ interface ListQuery {
     q?: string;
     /** Field key → coerced value; `null` means IS NULL. */
     filters: Record<string, string | number | boolean | null>;
+    /**
+     * Where to carry on from, instead of counting rows to skip. `OFFSET 500000` makes
+     * SQLite walk half a million index entries before it reads anything (8s at a million
+     * rows); a cursor turns that into a range scan (~100ms).
+     */
+    cursor?: Cursor;
+}
+/** The last row of the page you came from, and which way you're going. */
+interface Cursor {
+    /** The sort field's value on that row. */
+    value: string | number | boolean | null;
+    id: string;
+    direction: "after" | "before";
 }
 interface QueryIssue {
     param: string;
@@ -58,8 +71,18 @@ interface ListResult<T = Record<string, unknown>> {
     meta: {
         page: number;
         perPage: number;
+        /** Rows matching the query, counted up to `COUNT_LIMIT`. */
         total: number;
         totalPages: number;
+        /**
+         * Whether `total` is the real number. Counting every row of a large table on every
+         * page load is the single most expensive thing a list does, so the count stops at
+         * `COUNT_LIMIT` and says so; past that, the list pages by cursor.
+         */
+        exactTotal: boolean;
+        /** Carry on from the end of this page, and from its start, without an offset. */
+        nextCursor?: string;
+        prevCursor?: string;
     };
 }
 interface ChangeEvent {
@@ -70,6 +93,19 @@ interface ChangeEvent {
 }
 interface ResourceStoreOptions {
     resource: Resource;
+    /**
+     * Who is making the write, for the descriptor's hooks. The dashboard and the API both
+     * know; a seed doesn't, and passes nothing.
+     */
+    currentUser?: () => Promise<{
+        id: string;
+        email: string;
+        role?: string | null;
+    } | null> | {
+        id: string;
+        email: string;
+        role?: string | null;
+    } | null;
     table: SQLiteTable;
     getDb: () => AnyDatabase;
     /**
@@ -89,7 +125,7 @@ interface ResourceStoreOptions {
 declare function createResourceStore(options: ResourceStoreOptions): {
     resource: Resource<Record<string, Field>>;
     table: SQLiteTable<drizzle_orm_sqlite_core.TableConfig>;
-    /** `params`: page, perPage, sort, q, filter[field] (as parsed by parseListQuery). */
+    /** `params`: page, perPage, sort, q, filter[field], cursor (as parsed by parseListQuery). */
     list(params: URLSearchParams): Promise<Result<ListResult>>;
     get(id: string): Promise<Result<Record<string, unknown>>>;
     /** Title-field values for a set of ids (for showing relations). Missing ids are omitted. */
@@ -118,6 +154,8 @@ interface ResourceHandlerOptions {
     table: SQLiteTable;
     getDb: () => AnyDatabase;
     authorize: Authorize;
+    /** Who is making the request, for the descriptor's hooks. */
+    currentUser?: ResourceStoreOptions["currentUser"];
     /** Called after a write succeeds, for cache invalidation. */
     onChange?: (event: ChangeEvent) => void | Promise<void>;
 }

package/dist/server.js

@@ -2,7 +2,7 @@ import {
   can,
   createValidators,
   storedFields
-} from "./chunk-434JXSDV.js";
+} from "./chunk-PWP4QEZV.js";
 
 // ../../node_modules/.pnpm/drizzle-orm@0.45.2_@cloudfl_b372b29e6d5511672c7f9f9d2ac40572/node_modules/drizzle-orm/entity.js
 var entityKind = /* @__PURE__ */ Symbol.for("drizzle:entityKind");
@@ -1187,6 +1187,20 @@ function count(expression) {
 }
 
 // src/server/query.ts
+function encodeCursor(cursor) {
+  const json2 = JSON.stringify([cursor.value, cursor.id, cursor.direction === "before" ? 0 : 1]);
+  return btoa(json2).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeCursor(raw) {
+  try {
+    const json2 = atob(raw.replace(/-/g, "+").replace(/_/g, "/"));
+    const parsed = JSON.parse(json2);
+    if (!Array.isArray(parsed) || typeof parsed[1] !== "string") return void 0;
+    return { value: parsed[0], id: parsed[1], direction: parsed[2] === 0 ? "before" : "after" };
+  } catch {
+    return void 0;
+  }
+}
 var TIMESTAMP_FIELDS = ["createdAt", "updatedAt"];
 var MAX_PER_PAGE = 100;
 var MAX_SEARCH_LENGTH = 200;
@@ -1239,6 +1253,12 @@ function parseListQuery(resource, params) {
     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 rawCursor = params.get("cursor");
+  let cursor;
+  if (rawCursor) {
+    cursor = decodeCursor(rawCursor);
+    if (!cursor) issues.push({ param: "cursor", message: "isn't a cursor this list handed out" });
+  }
   const filters = {};
   for (const [name, raw] of params) {
     const match = /^filter\[(.+)\]$/.exec(name);
@@ -1253,10 +1273,17 @@ function parseListQuery(resource, params) {
     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 } };
+  return issues.length ? { issues } : { query: { page, perPage, sort, q, filters, cursor } };
 }
 
 // src/server/store.ts
+var COUNT_LIMIT = 1e4;
+function toCursorValue(value) {
+  if (value instanceof Date) return value.getTime();
+  if (value === null || value === void 0) return null;
+  if (typeof value === "object") return String(value);
+  return value;
+}
 function errorText(error) {
   const parts = [];
   for (let current = error, depth = 0; current && depth < 5; depth++) {
@@ -1322,14 +1349,29 @@ function createResourceStore(options) {
   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.`);
+  const computed = Object.entries(resource.computed ?? {});
+  const withComputed = (row) => {
+    if (computed.length === 0) return row;
+    const result = { ...row };
+    for (const [key, compute] of computed) {
+      try {
+        result[key] = compute(row);
+      } catch {
+        result[key] = null;
+      }
+    }
+    return result;
+  };
+  const hooks = resource.hooks ?? {};
+  const hookContext = async () => ({ db: getDb(), user: await options.currentUser?.() ?? null });
   return {
     resource,
     table,
-    /** `params`: page, perPage, sort, q, filter[field] (as parsed by parseListQuery). */
+    /** `params`: page, perPage, sort, q, filter[field], cursor (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 { page, perPage, sort, q, filters, cursor } = parsed.query;
       const conditions = [];
       if (q) {
         const pattern = `%${q.replace(/[\\%_]/g, (char) => `\\${char}`)}%`;
@@ -1339,22 +1381,56 @@ function createResourceStore(options) {
       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 filterWhere = conditions.length ? and(...conditions) : void 0;
+      const sortColumn = columns[sort.field];
+      const backwards = cursor?.direction === "before";
+      const descending = backwards ? sort.direction === "asc" : sort.direction === "desc";
+      const order = descending ? [desc(sortColumn), desc(idColumn)] : [asc(sortColumn), asc(idColumn)];
+      const pageConditions = [...conditions];
+      if (cursor) {
+        const value = cursor.value;
+        pageConditions.push(
+          descending ? or(sql`${sortColumn} < ${value}`, and(sql`${sortColumn} = ${value}`, sql`${idColumn} < ${cursor.id}`)) : or(sql`${sortColumn} > ${value}`, and(sql`${sortColumn} = ${value}`, sql`${idColumn} > ${cursor.id}`))
+        );
+      }
+      const where = pageConditions.length ? and(...pageConditions) : void 0;
       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 query = db.select().from(table).where(where).orderBy(...order).limit(perPage + 1);
+      const [found, counted] = await Promise.all([
+        cursor ? query : query.offset((page - 1) * perPage),
+        // One row past the limit is enough to know there's more without counting it all.
+        db.select({ total: count() }).from(db.select({ id: idColumn }).from(table).where(filterWhere).limit(COUNT_LIMIT + 1).as("capped"))
       ]);
-      const total = totals[0]?.total ?? 0;
+      const hasMore = found.length > perPage;
+      const rows = (hasMore ? found.slice(0, perPage) : found).map(withComputed);
+      if (backwards) rows.reverse();
+      const counting = counted[0]?.total ?? 0;
+      const exactTotal = counting <= COUNT_LIMIT;
+      const total = exactTotal ? counting : COUNT_LIMIT;
+      const first = rows[0];
+      const last = rows[rows.length - 1];
+      const moreAfter = backwards ? true : hasMore;
+      const moreBefore = backwards ? hasMore : Boolean(cursor) || page > 1;
+      const cursorFor = (row, direction) => row ? encodeCursor({ value: toCursorValue(row[sort.field]), id: String(row.id), direction }) : void 0;
       return {
         ok: true,
-        data: { data: rows, meta: { page, perPage, total, totalPages: Math.max(1, Math.ceil(total / perPage)) } }
+        data: {
+          data: rows,
+          meta: {
+            page,
+            perPage,
+            total,
+            totalPages: Math.max(1, Math.ceil(total / perPage)),
+            exactTotal,
+            nextCursor: moreAfter ? cursorFor(last, "after") : void 0,
+            prevCursor: moreBefore ? cursorFor(first, "before") : void 0
+          }
+        }
       };
     },
     async get(id) {
       const [record] = await getDb().select().from(table).where(byId(id)).limit(1);
-      return record ? { ok: true, data: record } : notFound();
+      return record ? { ok: true, data: withComputed(record) } : notFound();
     },
     /** Title-field values for a set of ids (for showing relations). Missing ids are omitted. */
     async titles(ids) {
@@ -1368,9 +1444,13 @@ function createResourceStore(options) {
       const result = validators.create.safeParse(input);
       if (!result.success) return Promise.resolve(invalid(result.error.issues));
       return writing("create", async () => {
+        const context = await hookContext();
+        const input2 = hooks.beforeCreate ? await hooks.beforeCreate({ ...result.data }, context) : result.data;
         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 };
+        const [record] = await getDb().insert(table).values({ ...input2, id: crypto.randomUUID(), createdAt: now, updatedAt: now }).returning();
+        const saved = withComputed(record);
+        await hooks.afterCreate?.(saved, context);
+        return { ok: true, data: saved };
       });
     },
     /** Partial update (PATCH semantics). */
@@ -1378,8 +1458,15 @@ function createResourceStore(options) {
       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();
+        const context = await hookContext();
+        const [existing] = hooks.beforeUpdate || hooks.afterUpdate ? await getDb().select().from(table).where(byId(id)).limit(1) : [];
+        const current = existing ?? null;
+        const input2 = hooks.beforeUpdate ? await hooks.beforeUpdate({ ...result.data }, { ...context, id, current }) : result.data;
+        const [record] = await getDb().update(table).set({ ...input2, updatedAt: /* @__PURE__ */ new Date() }).where(byId(id)).returning();
+        if (!record) return notFound();
+        const saved = withComputed(record);
+        await hooks.afterUpdate?.(saved, { ...context, previous: current });
+        return { ok: true, data: saved };
       });
     },
     /** Full replacement (PUT semantics): omitted fields go back to their default, or null when optional. */
@@ -1393,13 +1480,20 @@ function createResourceStore(options) {
         }
         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();
+        return record ? { ok: true, data: withComputed(record) } : notFound();
       });
     },
     delete(id) {
       return writing("delete", async () => {
+        const context = await hookContext();
+        if (hooks.beforeDelete) {
+          const [existing] = await getDb().select().from(table).where(byId(id)).limit(1);
+          await hooks.beforeDelete({ ...context, id, current: existing ?? null });
+        }
         const deleted = await getDb().delete(table).where(byId(id)).returning({ id: idColumn });
-        return deleted.length ? { ok: true, data: { id } } : notFound();
+        if (deleted.length === 0) return notFound();
+        await hooks.afterDelete?.({ ...context, id });
+        return { ok: true, data: { id } };
       });
     }
   };
@@ -1625,8 +1719,16 @@ function openApiDocument(options) {
     },
     PageMeta: {
       type: "object",
-      properties: { page: { type: "integer" }, perPage: { type: "integer" }, total: { type: "integer" }, totalPages: { type: "integer" } },
-      required: ["page", "perPage", "total", "totalPages"]
+      properties: {
+        page: { type: "integer" },
+        perPage: { type: "integer" },
+        total: { type: "integer", description: "Matching rows, counted up to 10,000." },
+        totalPages: { type: "integer" },
+        exactTotal: { type: "boolean", description: "False when there are more than 10,000 matches; page with the cursors instead." },
+        nextCursor: { type: "string", description: "Pass as ?cursor= for the next page." },
+        prevCursor: { type: "string" }
+      },
+      required: ["page", "perPage", "total", "totalPages", "exactTotal"]
     }
   };
   const tags = [{ name: "Authentication", description: "Sign in here first: the session cookie authorizes every other request." }];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaredev/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Flare runtime: resource descriptors, field grammar, and Cloudflare-native helpers",
   "license": "MIT",
   "author": "Muke Johnbaptist",