@flaredev/core 0.3.0 → 0.4.1

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

@@ -1,6 +1,9 @@
 // src/resource/fields.ts
 var STRING_FORMATS = ["email", "url", "tel", "domain", "country", "color", "slug"];
 var FILE_CATEGORIES = {
+  // For a field that holds whatever someone has: a drive, an attachment, a backup.
+  // Nothing is checked beyond the size limit, so don't reach for it out of convenience.
+  any: ["*/*"],
   image: ["image/png", "image/jpeg", "image/gif", "image/webp", "image/avif"],
   pdf: ["application/pdf"],
   video: ["video/*"],
@@ -17,7 +20,18 @@ var FILE_CATEGORIES = {
     "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
     "application/vnd.oasis.opendocument.spreadsheet"
   ],
-  archive: ["application/zip"]
+  // Browsers disagree about what a .zip is — Windows sends x-zip-compressed — and an
+  // archive field that refuses an ordinary zip is no use, so the aliases are listed too.
+  archive: [
+    "application/zip",
+    "application/x-zip-compressed",
+    "application/x-zip",
+    "application/gzip",
+    "application/x-gzip",
+    "application/x-7z-compressed",
+    "application/vnd.rar",
+    "application/x-rar-compressed"
+  ]
 };
 function mimeTypesFor(accept) {
   return [...new Set(accept.flatMap((category) => FILE_CATEGORIES[category]))];
@@ -87,6 +101,13 @@ function pluralize(value) {
 
 // src/resource/define.ts
 var RESERVED_FIELD_NAMES = ["id", "createdAt", "updatedAt"];
+function clientResource(resource) {
+  const { hooks, computed, $types, ...rest } = resource;
+  void hooks;
+  void computed;
+  void $types;
+  return rest;
+}
 var ResourceDefinitionError = class extends Error {
   constructor(resource, message) {
     super(`Resource "${resource}": ${message}`);
@@ -152,6 +173,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,
@@ -382,6 +406,7 @@ export {
   humanize,
   pluralize,
   RESERVED_FIELD_NAMES,
+  clientResource,
   ResourceDefinitionError,
   defaultFieldLabel,
   defineResource,

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-DaKcWZ5g.js';
+export { B as BelongsToField, a as BooleanField, b as ClientResource, D as DEFAULT_FILE_MAX_BYTES, c as DateField, d as DateTimeField, E as EnumField, e as FILE_CATEGORIES, f as FieldKind, g as FieldValue, h as FileCategory, i as FileField, j as FloatField, H as HasManyField, I as IntField, M as MultiSelectField, P as Policy, k as PolicyAction, l as PolicyConfig, m as PolicyError, n as RESERVED_FIELD_NAMES, o as RecordOf, p as ResourceConfig, q as ResourceDefinitionError, r as STRING_FORMATS, s as StringField, t as StringFormat, T as TextField, u as allowedActions, v as can, w as clientResource, x as columnName, y as defaultFieldLabel, z as definePolicy, A as defineResource, G as field, J as fileMaxBytes, K as mimeTypesFor, L as storedFields } from './policy-DaKcWZ5g.js';
 import { z } from 'zod';
 
 /**
@@ -286,7 +286,7 @@ declare function fieldSchema(def: StoredField): z.ZodType;
  * edit a record could attach another resource's private file and read it through theirs.
  */
 declare const fileKeyPrefix: (resource: Pick<Resource, "table">, fieldKey: string) => string;
-declare function createValidators<Fields extends Record<string, Field>>(resource: Resource<Fields>): ResourceValidators<Fields>;
+declare function createValidators<Fields extends Record<string, Field>>(resource: Pick<Resource<Fields>, "fields" | "table">): ResourceValidators<Fields>;
 
 /** Naming helpers shared by descriptors and the generator. */
 /** "OrderItem" / "order item" / "order-item" → ["order", "item"] */
@@ -365,13 +365,13 @@ declare function formatValue(def: StoredField | {
  */
 type FormValues = Record<string, string | boolean>;
 /** Initial form state: the record's values (edit) or the descriptor's defaults (create). */
-declare function initialFormValues(resource: Resource, record?: Record<string, unknown> | null): FormValues;
+declare function initialFormValues(resource: Pick<Resource, "fields">, record?: Record<string, unknown> | null): FormValues;
 /**
  * API input from form state. Empty optional fields become null (clearing them);
  * empty fields that have a default are omitted on create so the default applies;
  * empty required fields are left for validation to report as "Required".
  */
-declare function formValuesToInput(resource: Resource, values: FormValues, mode: "create" | "edit"): Record<string, unknown>;
+declare function formValuesToInput(resource: Pick<Resource, "fields">, values: FormValues, mode: "create" | "edit"): Record<string, unknown>;
 /** A multiselect's form state (a JSON array string) as the picked values. */
 declare function parseMultiValue(raw: string | boolean | undefined): string[];
 /** Field errors keyed by field name, from validation or API issues (first message wins). */
@@ -439,6 +439,8 @@ interface Fake {
     email(name?: string): string;
     company(): string;
     jobTitle(): string;
+    /** "Brushed steel desk lamp", or a digital one: "Starter kit licence". */
+    product(digital?: boolean): string;
     city(): string;
     /** ISO 3166-1 alpha-2, e.g. "UG". */
     country(): string;
@@ -507,6 +509,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.1";
 
 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

@@ -8,6 +8,7 @@ import {
   allowedActions,
   camelCase,
   can,
+  clientResource,
   columnName,
   countries,
   countryName,
@@ -38,7 +39,7 @@ import {
   storedFields,
   toE164,
   words
-} from "./chunk-434JXSDV.js";
+} from "./chunk-VLHPSNQN.js";
 
 // src/password.ts
 var ALGORITHM = "pbkdf2-sha256";
@@ -241,6 +242,8 @@ var EMPTY_ZIP = [80, 75, 5, 6];
 var OLE2 = [208, 207, 17, 224, 161, 177, 26, 225];
 var EBML = [26, 69, 223, 163];
 var isZip = (head) => startsWith(head, ZIP) || startsWith(head, EMPTY_ZIP);
+var isGzip = (head) => startsWith(head, [31, 139]);
+var isRar = (head) => startsWith(head, ascii("Rar!"));
 var EXACT = {
   "image/png": (head) => startsWith(head, [137, 80, 78, 71, 13, 10, 26, 10]),
   "image/jpeg": (head) => startsWith(head, [255, 216, 255]),
@@ -249,6 +252,13 @@ var EXACT = {
   "image/avif": (head) => ["avif", "avis", "mif1", "msf1"].includes(isoBrand(head) ?? ""),
   "application/pdf": (head) => startsWith(head, ascii("%PDF-")),
   "application/zip": isZip,
+  "application/x-zip-compressed": isZip,
+  "application/x-zip": isZip,
+  "application/gzip": isGzip,
+  "application/x-gzip": isGzip,
+  "application/x-7z-compressed": (head) => startsWith(head, [55, 122, 188, 175, 39, 28]),
+  "application/vnd.rar": isRar,
+  "application/x-rar-compressed": isRar,
   // Office Open XML and OpenDocument files are zip archives.
   "application/vnd.openxmlformats-officedocument.wordprocessingml.document": isZip,
   "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": isZip,
@@ -281,6 +291,7 @@ function matchesContentType(contentType, allowed) {
   if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(type)) return false;
   return allowed.some((pattern) => {
     const p = pattern.trim().toLowerCase();
+    if (p === "*/*") return true;
     return p.endsWith("/*") ? type.startsWith(p.slice(0, -1)) : type === p;
   });
 }
@@ -873,6 +884,26 @@ var WORDS = [
   "variance",
   "workflow"
 ];
+var PRODUCT_QUALITIES = ["Oak", "Walnut", "Brushed steel", "Canvas", "Merino", "Recycled", "Matte black", "Linen", "Copper", "Frosted glass"];
+var PRODUCT_THINGS = [
+  "desk lamp",
+  "office chair",
+  "notebook",
+  "water bottle",
+  "backpack",
+  "keyboard",
+  "mouse mat",
+  "coffee grinder",
+  "travel mug",
+  "wall clock",
+  "storage box",
+  "cable tidy",
+  "monitor stand",
+  "planter",
+  "door mat",
+  "tote bag"
+];
+var DIGITAL_THINGS = ["starter kit", "source code licence", "icon pack", "template bundle", "course", "font family", "preset pack", "e-book"];
 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"];
@@ -924,6 +955,7 @@ function createFake(seed = 20260101) {
       return `${slugify2(local).replace(/-/g, ".")}${step()}@${pick(DOMAINS)}`;
     },
     company: () => `${pick(COMPANY_HEADS)} ${pick(COMPANY_TAILS)}`,
+    product: (digital = false) => digital ? `${pick(PRODUCT_QUALITIES)} ${pick(DIGITAL_THINGS)}` : `${pick(PRODUCT_QUALITIES)} ${pick(PRODUCT_THINGS)}`,
     jobTitle: () => `${pick(["Head of", "Senior", "Lead", "Regional", "Junior"])} ${pick(["Operations", "Sales", "Support", "Engineering", "Finance", "Logistics"])}`,
     city: () => pick(CITIES),
     country: () => pick(COUNTRIES)[0],
@@ -962,7 +994,7 @@ function createFake(seed = 20260101) {
 var fake = createFake();
 
 // src/index.ts
-var FLARE_VERSION = "0.3.0";
+var FLARE_VERSION = "0.4.1";
 export {
   DEFAULT_FILE_MAX_BYTES,
   FILE_CATEGORIES,
@@ -979,6 +1011,7 @@ export {
   camelCase,
   can,
   checkoutPaid,
+  clientResource,
   columnName,
   countries,
   countryName,

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

@@ -116,6 +116,7 @@ type Field = StringField | TextField | IntField | FloatField | BooleanField | Da
 type StoredField = Exclude<Field, HasManyField>;
 /** File categories usable in `file:[...]` and the MIME types each allows. */
 declare const FILE_CATEGORIES: {
+    readonly any: readonly ["*/*"];
     readonly image: readonly ["image/png", "image/jpeg", "image/gif", "image/webp", "image/avif"];
     readonly pdf: readonly ["application/pdf"];
     readonly video: readonly ["video/*"];
@@ -124,7 +125,7 @@ declare const FILE_CATEGORIES: {
     readonly csv: readonly ["text/csv"];
     readonly document: readonly ["application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.oasis.opendocument.text"];
     readonly spreadsheet: readonly ["application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.oasis.opendocument.spreadsheet"];
-    readonly archive: readonly ["application/zip"];
+    readonly archive: readonly ["application/zip", "application/x-zip-compressed", "application/x-zip", "application/gzip", "application/x-gzip", "application/x-7z-compressed", "application/vnd.rar", "application/x-rar-compressed"];
 };
 type FileCategory = keyof typeof FILE_CATEGORIES;
 declare function mimeTypesFor(accept: readonly FileCategory[]): string[];
@@ -223,6 +224,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 +237,53 @@ 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. It runs *before* validation, so it can fill in a field the caller
+     * couldn't supply — an order number, a slug — and what it returns is then validated.
+     */
+    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 +292,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;
@@ -256,6 +312,22 @@ interface Resource<Fields extends Record<string, Field> = Record<string, Field>>
         record: RecordOf<Fields>;
     };
 }
+/**
+ * A resource as a client component can receive it: everything that describes the fields,
+ * without the code.
+ *
+ * `hooks` and `computed` hold functions, and a function can't cross from the server to
+ * the browser — React refuses a prop it wasn't told to expose, and the page fails to
+ * render. So a server component hands a client one `clientResource(resource)` instead.
+ * The `never` types below turn passing the whole resource into a type error, which is
+ * cheaper to find than the runtime one.
+ */
+type ClientResource<Fields extends Record<string, Field> = Record<string, Field>> = Omit<Resource<Fields>, "hooks" | "computed" | "$types"> & {
+    hooks?: never;
+    computed?: never;
+};
+/** The parts of a resource that are safe to send to the browser. */
+declare function clientResource<Fields extends Record<string, Field>>(resource: Resource<Fields>): ClientResource<Fields>;
 declare class ResourceDefinitionError extends Error {
     constructor(resource: string, message: string);
 }
@@ -263,7 +335,7 @@ declare class ResourceDefinitionError extends Error {
 declare function defaultFieldLabel(key: string, field: Field): string;
 declare function defineResource<const Fields extends Record<string, Field>>(config: ResourceConfig<Fields>): Resource<Fields>;
 /** Stored (column-backed) fields of a resource, in declaration order. */
-declare function storedFields(resource: Resource): [string, StoredField & {
+declare function storedFields(resource: Pick<Resource, "fields">): [string, StoredField & {
     label: string;
 }][];
 /** Database column name for a field key ("companyId" → "company_id"). */
@@ -305,4 +377,4 @@ declare function can(policy: Policy | undefined | null, role: string | null | un
 /** Actions `role` may perform, for hiding UI it can't use. */
 declare function allowedActions(policy: Policy | undefined | null, role: string | null | undefined): Record<Exclude<PolicyAction, "list">, boolean>;
 
-export { fileMaxBytes as A, type BelongsToField as B, type CreateInput as C, DEFAULT_FILE_MAX_BYTES as D, type EnumField as E, type Field as F, mimeTypesFor as G, type HasManyField as H, type IntField as I, storedFields as J, type MultiSelectField as M, type Policy as P, type Resource as R, type StoredField as S, type TextField as T, type UpdateInput as U, type BooleanField as a, type DateField as b, type DateTimeField as c, FILE_CATEGORIES as d, type FieldKind as e, type FieldValue as f, type FileCategory as g, type FileField as h, type FloatField as i, type PolicyAction as j, type PolicyConfig as k, PolicyError as l, RESERVED_FIELD_NAMES as m, type RecordOf as n, type ResourceConfig as o, ResourceDefinitionError as p, STRING_FORMATS as q, type StringField as r, type StringFormat as s, allowedActions as t, can as u, columnName as v, defaultFieldLabel as w, definePolicy as x, defineResource as y, field as z };
+export { defineResource as A, type BelongsToField as B, type CreateInput as C, DEFAULT_FILE_MAX_BYTES as D, type EnumField as E, type Field as F, field as G, type HasManyField as H, type IntField as I, fileMaxBytes as J, mimeTypesFor as K, storedFields as L, type MultiSelectField as M, type Policy as P, type Resource as R, type StoredField as S, type TextField as T, type UpdateInput as U, type BooleanField as a, type ClientResource as b, type DateField as c, type DateTimeField as d, FILE_CATEGORIES as e, type FieldKind as f, type FieldValue as g, type FileCategory as h, type FileField as i, type FloatField as j, type PolicyAction as k, type PolicyConfig as l, PolicyError as m, RESERVED_FIELD_NAMES as n, type RecordOf as o, type ResourceConfig as p, ResourceDefinitionError as q, STRING_FORMATS as r, type StringField as s, type StringFormat as t, allowedActions as u, can as v, clientResource as w, columnName as x, defaultFieldLabel as y, definePolicy as z };

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-DaKcWZ5g.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,14 +125,14 @@ 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. */
     titles(ids: string[]): Promise<Record<string, string>>;
-    create(input: unknown): Promise<Result<Record<string, unknown>>>;
+    create(raw: unknown): Promise<Result<Record<string, unknown>>>;
     /** Partial update (PATCH semantics). */
-    update(id: string, input: unknown): Promise<Result<Record<string, unknown>>>;
+    update(id: string, raw: unknown): Promise<Result<Record<string, unknown>>>;
     /** Full replacement (PUT semantics): omitted fields go back to their default, or null when optional. */
     replace(id: string, input: unknown): Promise<Result<Record<string, unknown>>>;
     delete(id: string): Promise<Result<{
@@ -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>;
 }
@@ -144,8 +182,8 @@ declare function createResourceHandlers(options: ResourceHandlerOptions): {
         list(params: URLSearchParams): Promise<Result<ListResult>>;
         get(id: string): Promise<Result<Record<string, unknown>>>;
         titles(ids: string[]): Promise<Record<string, string>>;
-        create(input: unknown): Promise<Result<Record<string, unknown>>>;
-        update(id: string, input: unknown): Promise<Result<Record<string, unknown>>>;
+        create(raw: unknown): Promise<Result<Record<string, unknown>>>;
+        update(id: string, raw: unknown): Promise<Result<Record<string, unknown>>>;
         replace(id: string, input: unknown): Promise<Result<Record<string, unknown>>>;
         delete(id: string): Promise<Result<{
             id: string;

package/dist/server.js

@@ -2,7 +2,7 @@ import {
   can,
   createValidators,
   storedFields
-} from "./chunk-434JXSDV.js";
+} from "./chunk-VLHPSNQN.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) {
@@ -1364,22 +1440,35 @@ function createResourceStore(options) {
       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));
+    create(raw) {
       return writing("create", async () => {
+        const context = await hookContext();
+        const supplied = hooks.beforeCreate ? await hooks.beforeCreate({ ...raw ?? {} }, context) : raw;
+        const result = validators.create.safeParse(supplied);
+        if (!result.success) return invalid(result.error.issues);
+        const input = 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({ ...input, 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). */
-    update(id, input) {
-      const result = validators.update.safeParse(input);
-      if (!result.success) return Promise.resolve(invalid(result.error.issues));
+    update(id, raw) {
       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 supplied = hooks.beforeUpdate ? await hooks.beforeUpdate({ ...raw ?? {} }, { ...context, id, current }) : raw;
+        const result = validators.update.safeParse(supplied);
+        if (!result.success) return invalid(result.error.issues);
+        const input = result.data;
+        const [record] = await getDb().update(table).set({ ...input, 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 +1482,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 +1721,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.1",
   "description": "Flare runtime: resource descriptors, field grammar, and Cloudflare-native helpers",
   "license": "MIT",
   "author": "Muke Johnbaptist",