@flaredev/core 0.2.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';
 
 /**
@@ -413,26 +413,100 @@ declare const isSlug: (value: string) => boolean;
 /** "My First Post!" → "my-first-post". */
 declare function slugify(value: string): string;
 
+/**
+ * Sample data for seeds. Small on purpose: a handful of word lists and a seeded
+ * random number generator, so a million rows cost nothing to produce and the same
+ * seed always gives the same data.
+ *
+ *   const fake = createFake();
+ *   fake.fullName();  // "Amina Okello"
+ *   fake.email();     // "amina.okello4@example.com"
+ */
+interface Fake {
+    /** Whole number in [min, max]. */
+    int(min: number, max: number): number;
+    /** Number in [min, max], rounded to `decimals` places (default 2). */
+    float(min: number, max: number, decimals?: number): number;
+    /** True with the given probability (default 0.5). */
+    bool(chance?: number): boolean;
+    pick<T>(items: readonly T[]): T;
+    /** Between `min` and `max` distinct items, in the order they appear. */
+    some<T>(items: readonly T[], min?: number, max?: number): T[];
+    firstName(): string;
+    lastName(): string;
+    fullName(): string;
+    /** A unique address: the counter keeps it unique however many rows are made. */
+    email(name?: string): string;
+    company(): string;
+    jobTitle(): string;
+    city(): string;
+    /** ISO 3166-1 alpha-2, e.g. "UG". */
+    country(): string;
+    /** E.164, e.g. "+256772431980". */
+    phone(): string;
+    domain(): string;
+    url(): string;
+    slug(text?: string): string;
+    color(): string;
+    words(count?: number): string;
+    sentence(): string;
+    paragraph(sentences?: number): string;
+    /** "YYYY-MM-DD" within the last `daysBack` days (default 365). */
+    date(daysBack?: number): string;
+    /** ISO timestamp within the last `daysBack` days (default 365). */
+    datetime(daysBack?: number): string;
+    /** Milliseconds since the epoch, within the last `daysBack` days. */
+    timestamp(daysBack?: number): number;
+    uuid(): string;
+    /**
+     * A ULID: a 26-character id that sorts by the time it was made. Rows seeded with
+     * these go in at the end of the primary key's index instead of all over it, which
+     * measured 4× quicker than random ids at a few hundred thousand rows.
+     */
+    id(): string;
+    /** How many values this generator has produced; unique per row. */
+    readonly count: number;
+}
+/**
+ * A generator of sample values. `seed` makes runs reproducible; leave it out for a
+ * different set every time.
+ */
+declare function createFake(seed?: number): Fake;
+/** A shared generator, for seeds that don't need their own. */
+declare const fake: Fake;
+
 /**
  * Seed files: `seeds/<name>.seed.ts`, run by `flare seed` against the local D1 database.
  *
  *   import { defineSeed } from "@flaredev/core";
  *   import { contacts } from "@/db/schema";
  *
- *   export default defineSeed(async ({ db }) => {
+ *   export default defineSeed(async ({ db, insertMany, fake }) => {
  *     await db.insert(contacts).values([{ name: "Ada", email: "ada@example.com" }]);
+ *     await insertMany(contacts, 10_000, () => ({ name: fake.fullName(), email: fake.email() }));
  *   });
  */
+
+/**
+ * Insert many rows at once. `rows` is either the rows themselves or a function called
+ * once per row, which keeps a million rows out of memory. Far quicker than a Drizzle
+ * insert of the same size: the values go into the SQL rather than into D1's
+ * 100-parameter budget.
+ */
+type InsertMany = <T extends object>(table: unknown, count: number | readonly T[], build?: (index: number) => T) => Promise<number>;
 interface SeedContext {
     /** Drizzle client over the app's schema, bound to the local D1 database. */
     db: any;
     /** All local bindings and variables (D1, R2, .dev.vars). */
     env: Record<string, unknown>;
     log: (message: string) => void;
+    insertMany: InsertMany;
+    /** Sample values: names, emails, sentences, dates. */
+    fake: Fake;
 }
 type Seed = (context: SeedContext) => void | Promise<void>;
 declare function defineSeed(seed: Seed): Seed;
 
-declare const FLARE_VERSION = "0.2.0";
+declare const FLARE_VERSION = "0.4.0";
 
-export { type BelongsToRelation, type Country, CreateInput, FLARE_VERSION, Field, type FormValues, type FormatOptions, type HasManyRelation, 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, createMailer, createObjectKey, createStorage, createValidators, currentPeriodEnd, defineSeed, 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 };
+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";
@@ -673,8 +673,296 @@ function defineSeed(seed) {
   return seed;
 }
 
+// src/fake.ts
+var FIRST_NAMES = [
+  "Amina",
+  "Daniel",
+  "Grace",
+  "Wei",
+  "Sofia",
+  "Tendai",
+  "Noah",
+  "Priya",
+  "Lucas",
+  "Fatima",
+  "Ibrahim",
+  "Elena",
+  "Kwame",
+  "Maya",
+  "Hiroshi",
+  "Leila",
+  "Marcus",
+  "Chiara",
+  "Omar",
+  "Ana",
+  "Joseph",
+  "Nadia",
+  "Thabo",
+  "Yuki",
+  "Diego",
+  "Ruth",
+  "Samuel",
+  "Zara",
+  "Peter",
+  "Isabel",
+  "Kofi",
+  "Mei",
+  "Andr\xE9s",
+  "Halima",
+  "Jonas",
+  "Rania",
+  "Esther",
+  "Viktor",
+  "Aisha",
+  "Tom\xE1s"
+];
+var LAST_NAMES = [
+  "Okello",
+  "Silva",
+  "Nakamura",
+  "Mensah",
+  "Okafor",
+  "Rossi",
+  "Chen",
+  "Hassan",
+  "M\xFCller",
+  "Dubois",
+  "Kimani",
+  "Patel",
+  "Novak",
+  "Garcia",
+  "Haddad",
+  "Andersen",
+  "Osei",
+  "Reyes",
+  "Kowalski",
+  "Tadesse",
+  "Nguyen",
+  "Baptiste",
+  "Mwangi",
+  "Fernandes",
+  "Ivanov",
+  "Khan",
+  "Lindqvist",
+  "Santos",
+  "Abebe",
+  "Yusuf"
+];
+var COMPANY_HEADS = [
+  "North",
+  "Blue",
+  "Bright",
+  "Iron",
+  "River",
+  "Summit",
+  "Atlas",
+  "Harbour",
+  "Cedar",
+  "Copper",
+  "Lumen",
+  "Orbit",
+  "Stone",
+  "Vertex",
+  "Willow",
+  "Zenith",
+  "Kestrel",
+  "Meridian",
+  "Sable",
+  "Terra"
+];
+var COMPANY_TAILS = ["Labs", "Works", "Group", "Studio", "Systems", "Partners", "Supply", "Analytics", "Foods", "Logistics"];
+var CITIES = [
+  "Kampala",
+  "Nairobi",
+  "Lagos",
+  "Accra",
+  "Cairo",
+  "Cape Town",
+  "Dar es Salaam",
+  "Casablanca",
+  "London",
+  "Berlin",
+  "Madrid",
+  "Lisbon",
+  "Warsaw",
+  "Stockholm",
+  "Amsterdam",
+  "Dublin",
+  "New York",
+  "Toronto",
+  "Chicago",
+  "Austin",
+  "S\xE3o Paulo",
+  "Bogot\xE1",
+  "Mexico City",
+  "Lima",
+  "Mumbai",
+  "Singapore",
+  "Tokyo",
+  "Seoul",
+  "Jakarta",
+  "Manila",
+  "Sydney",
+  "Auckland"
+];
+var COUNTRIES = [
+  ["UG", "256"],
+  ["KE", "254"],
+  ["NG", "234"],
+  ["GH", "233"],
+  ["ZA", "27"],
+  ["EG", "20"],
+  ["US", "1"],
+  ["CA", "1"],
+  ["GB", "44"],
+  ["IE", "353"],
+  ["DE", "49"],
+  ["FR", "33"],
+  ["ES", "34"],
+  ["PT", "351"],
+  ["NL", "31"],
+  ["SE", "46"],
+  ["PL", "48"],
+  ["BR", "55"],
+  ["MX", "52"],
+  ["IN", "91"],
+  ["SG", "65"],
+  ["JP", "81"],
+  ["AU", "61"],
+  ["AE", "971"]
+];
+var WORDS = [
+  "account",
+  "balance",
+  "shipment",
+  "invoice",
+  "review",
+  "signal",
+  "request",
+  "channel",
+  "vendor",
+  "budget",
+  "report",
+  "delivery",
+  "contract",
+  "renewal",
+  "forecast",
+  "meeting",
+  "proposal",
+  "discount",
+  "refund",
+  "ticket",
+  "quarter",
+  "pipeline",
+  "customer",
+  "supplier",
+  "warehouse",
+  "campaign",
+  "segment",
+  "retention",
+  "onboarding",
+  "escalation",
+  "follow-up",
+  "handover",
+  "kickoff",
+  "milestone",
+  "rollout",
+  "shortfall",
+  "surplus",
+  "threshold",
+  "variance",
+  "workflow"
+];
+var DOMAINS = ["example.com", "example.org", "example.net", "mail.example.com"];
+var TLDS = ["com", "io", "co", "org", "net"];
+var COLORS = ["#f2541d", "#2563eb", "#16a34a", "#d97706", "#7c3aed", "#0891b2", "#db2777", "#4b5563"];
+var DAY_MS = 864e5;
+var CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function encodeCrockford(value, length) {
+  let out = "";
+  let rest = value;
+  for (let i = 0; i < length; i++) {
+    out = CROCKFORD[Number(rest % 32n)] + out;
+    rest /= 32n;
+  }
+  return out;
+}
+function random(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = state + 1831565813 >>> 0;
+    let t = Math.imul(state ^ state >>> 15, 1 | state);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function createFake(seed = 20260101) {
+  const next = random(seed);
+  let count = 0;
+  const step = () => ++count;
+  const tail = BigInt(Math.floor(next() * 2 ** 40)) * 2n ** 40n;
+  let counter = 0n;
+  const int = (min, max) => min + Math.floor(next() * (max - min + 1));
+  const pick = (items) => items[Math.floor(next() * items.length)];
+  const slugify2 = (text2) => text2.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  const fake2 = {
+    int,
+    float: (min, max, decimals = 2) => Number((min + next() * (max - min)).toFixed(decimals)),
+    bool: (chance = 0.5) => next() < chance,
+    pick,
+    some(items, min = 1, max = items.length) {
+      const wanted = int(Math.min(min, items.length), Math.min(max, items.length));
+      const chosen = /* @__PURE__ */ new Set();
+      while (chosen.size < wanted) chosen.add(Math.floor(next() * items.length));
+      return [...chosen].sort((a, b) => a - b).map((index) => items[index]);
+    },
+    firstName: () => pick(FIRST_NAMES),
+    lastName: () => pick(LAST_NAMES),
+    fullName: () => `${pick(FIRST_NAMES)} ${pick(LAST_NAMES)}`,
+    email(name) {
+      const local = name ? slugify2(name).replace(/-/g, ".") : `${pick(FIRST_NAMES)}.${pick(LAST_NAMES)}`.toLowerCase();
+      return `${slugify2(local).replace(/-/g, ".")}${step()}@${pick(DOMAINS)}`;
+    },
+    company: () => `${pick(COMPANY_HEADS)} ${pick(COMPANY_TAILS)}`,
+    jobTitle: () => `${pick(["Head of", "Senior", "Lead", "Regional", "Junior"])} ${pick(["Operations", "Sales", "Support", "Engineering", "Finance", "Logistics"])}`,
+    city: () => pick(CITIES),
+    country: () => pick(COUNTRIES)[0],
+    phone: () => `+${pick(COUNTRIES)[1]}${String(int(7e8, 799999999))}`,
+    domain: () => `${slugify2(`${pick(COMPANY_HEADS)}${pick(COMPANY_TAILS)}`)}${step()}.${pick(TLDS)}`,
+    url: () => `https://${slugify2(pick(COMPANY_HEADS))}.${pick(TLDS)}/${slugify2(pick(WORDS))}`,
+    slug: (text2) => `${slugify2(text2 ?? `${pick(WORDS)}-${pick(WORDS)}`)}-${step()}`,
+    color: () => pick(COLORS),
+    words: (howMany = 3) => Array.from({ length: howMany }, () => pick(WORDS)).join(" "),
+    sentence() {
+      const words2 = Array.from({ length: int(5, 12) }, () => pick(WORDS)).join(" ");
+      return `${words2[0].toUpperCase()}${words2.slice(1)}.`;
+    },
+    paragraph(sentences = 3) {
+      return Array.from({ length: sentences }, () => fake2.sentence()).join(" ");
+    },
+    timestamp: (daysBack = 365) => Date.now() - int(0, daysBack) * DAY_MS - int(0, DAY_MS - 1),
+    date: (daysBack = 365) => new Date(fake2.timestamp(daysBack)).toISOString().slice(0, 10),
+    datetime: (daysBack = 365) => new Date(fake2.timestamp(daysBack)).toISOString(),
+    uuid() {
+      const hex = "0123456789abcdef";
+      let out = "";
+      for (let i = 0; i < 32; i++) out += hex[Math.floor(next() * 16)];
+      return `${out.slice(0, 8)}-${out.slice(8, 12)}-4${out.slice(13, 16)}-a${out.slice(17, 20)}-${out.slice(20, 32)}`;
+    },
+    id() {
+      counter += 1n;
+      return encodeCrockford(BigInt(Date.now()), 10) + encodeCrockford((tail + counter) % 2n ** 80n, 16);
+    },
+    get count() {
+      return count;
+    }
+  };
+  return fake2;
+}
+var fake = createFake();
+
 // src/index.ts
-var FLARE_VERSION = "0.2.0";
+var FLARE_VERSION = "0.4.0";
 export {
   DEFAULT_FILE_MAX_BYTES,
   FILE_CATEGORIES,
@@ -694,6 +982,7 @@ export {
   columnName,
   countries,
   countryName,
+  createFake,
   createMailer,
   createObjectKey,
   createStorage,
@@ -703,6 +992,7 @@ export {
   definePolicy,
   defineResource,
   defineSeed,
+  fake,
   field,
   fieldSchema,
   fileKeyPrefix,

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.2.0",
+  "version": "0.4.0",
   "description": "Flare runtime: resource descriptors, field grammar, and Cloudflare-native helpers",
   "license": "MIT",
   "author": "Muke Johnbaptist",