@isaijs/core 0.1.5 → 0.1.8

package/dist/{index-D0FEnMhn.d.ts → index-Bb9Px6SR.d.ts}

@@ -1,7 +1,7 @@
-import { a as DatabaseDriver, b as TenantDatabases, d as RateLimiter, g as Storage, l as PdfRenderer, n as Body, p as Runtime, r as Cache, s as MailDriver, u as Queue } from "./index-Ce5p2-EB.js";
-import { C as ObjectShape, Y as StoredFile, w as Output } from "./index-CYcklQ1l.js";
-import { $ as Expr, C as WithIncludes, D as PageOptions, E as Page, J as Models, Q as Embed, S as Key, T as NumberedPageOptions, V as AnyModel, X as Condition, Z as Conditional, b as RowOf, ct as ColumnNode, gt as FieldSpec, i as Row, lt as ConditionNode, n as Patch, p as Database, t as Insert, u as Seed, ut as Operand, v as OrderKey, w as NumberedPage, x as IncludePath } from "./types-BgOkJy5d.js";
-import { a as PROVIDERS, i as HELD, k as Manifest } from "./data-layer-43pme0Gy.js";
+import { a as DatabaseDriver, b as TenantDatabases, d as RateLimiter, f as Row, g as Storage, l as PdfRenderer, n as Body, p as Runtime, r as Cache, s as MailDriver, u as Queue } from "./index-Ce5p2-EB.js";
+import { C as ObjectShape, Y as StoredFile, w as Output } from "./index-CaR3hb0i.js";
+import { $ as Expr, C as WithIncludes, D as PageOptions, E as Page, J as Models, O as Write, Q as Embed, S as Key, T as NumberedPageOptions, V as AnyModel, X as Condition, Z as Conditional, b as RowOf, ct as ColumnNode, gt as FieldSpec, i as Row$1, lt as ConditionNode, n as Patch, p as Database, t as Insert, u as Seed, ut as Operand, v as OrderKey, w as NumberedPage, x as IncludePath } from "./types-D5SIVeej.js";
+import { a as PROVIDERS, i as HELD, k as Manifest } from "./data-layer-nvm_ivGQ.js";
 //#region src/api/fail.d.ts
 /**
  * `fail(code, message)`: the app's own business rules, for what can't be a `.check()`, a flow or a
@@ -33,10 +33,10 @@ interface BuiltinUser {
 }
 type UserRow = Models extends {
   readonly User: infer U extends AnyModel;
-} ? Row<U> : BuiltinUser;
+} ? Row$1<U> : BuiltinUser;
 type TenantRow$1 = Models extends {
   readonly Tenant: infer T extends AnyModel;
-} ? Row<T> : {
+} ? Row$1<T> : {
   readonly id: string;
   readonly name: string;
 };
@@ -133,12 +133,12 @@ type Simplify<T> = { [K in keyof T]: T[K]; } & {};
 type OwnedInsert<M extends AnyModel> = Simplify<Omit<Insert<M>, OwnerKeys<M>> & Partial<Pick<Insert<M>, OwnerKeys<M> & keyof Insert<M>>>>;
 /** The route context's `db`. Transactions, upserts and raw SQL are for services (`app.db`). */
 interface RouteDatabase {
-  findOne<M extends AnyModel>(model: M, key: Key<M>): CheckedOne<M, Row<M>>;
-  findMany<M extends AnyModel>(model: M): CheckedQuery<M, Row<M>>;
-  createOne<M extends AnyModel>(model: M, input: OwnedInsert<M>): Ends<Row<M>>;
-  createMany<M extends AnyModel>(model: M, inputs: readonly OwnedInsert<M>[]): Ends<Row<M>[]>;
-  updateOne<M extends AnyModel>(model: M, key: Key<M>, patch: Patch<M>): CheckedMaybe<Row<M>>;
-  deleteOne<M extends AnyModel>(model: M, key: Key<M>): CheckedMaybe<Row<M>>;
+  findOne<M extends AnyModel>(model: M, key: Key<M>): CheckedOne<M, Row$1<M>>;
+  findMany<M extends AnyModel>(model: M): CheckedQuery<M, Row$1<M>>;
+  createOne<M extends AnyModel>(model: M, input: OwnedInsert<M>): Ends<Row$1<M>>;
+  createMany<M extends AnyModel>(model: M, inputs: readonly OwnedInsert<M>[]): Ends<Row$1<M>[]>;
+  updateOne<M extends AnyModel>(model: M, key: Key<M>, patch: Patch<M>): CheckedMaybe<Row$1<M>>;
+  deleteOne<M extends AnyModel>(model: M, key: Key<M>): CheckedMaybe<Row$1<M>>;
   updateMany<M extends AnyModel>(model: M, patch: Patch<M>): CheckedMany<M>;
   deleteMany<M extends AnyModel>(model: M): CheckedMany<M>;
 }
@@ -153,7 +153,7 @@ type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  */
 type User = Models extends {
   readonly User: infer U extends AnyModel;
-} ? Row<U> : {
+} ? Row$1<U> : {
   readonly id: string;
 };
 /**
@@ -162,7 +162,7 @@ type User = Models extends {
  */
 type PlatformUser = Models extends {
   readonly PlatformUser: infer U extends AnyModel;
-} ? Row<U> : {
+} ? Row$1<U> : {
   readonly id: string;
 };
 type ParamNames<P extends string> = P extends `${string}:${infer Name}/${infer Rest}` ? Name | ParamNames<`/${Rest}`> : P extends `${string}:${infer Name}` ? Name : never;
@@ -178,14 +178,28 @@ interface RouteOptions<S extends ObjectShape = ObjectShape, A extends boolean =
    * the platform's, `user` a platform user.
    */
   readonly platform?: Pl;
+  /**
+   * Runs before each upload to this route's file inputs is stored, once its size and type are
+   * known: throw (`fail`) to refuse it. `pending` is the bytes of every upload not yet attached, so
+   * a cap counts them: `upload: async (_, { size, pending }) => { if (used() + pending + size > cap) fail(…) }`.
+   */
+  readonly upload?: UploadCheck<A, Pl>;
+}
+/** An upload about to be stored: its route input's key, bytes, media type, and the bytes pending. */
+interface UploadInfo {
+  readonly field: string;
+  readonly size: number;
+  readonly type: string;
+  readonly pending: number;
 }
+type UploadCheck<A extends boolean = boolean, Pl extends boolean = boolean> = (context: RouteContext<string, Record<never, never>, A, Pl>, upload: UploadInfo) => unknown;
 /**
  * The current tenant's row, with tenancy: the app's `Tenant` (its own columns too) once it's in the
  * `Models` registry; `undefined` in a single-tenant app.
  */
 type TenantRow = Models extends {
   readonly Tenant: infer T extends AnyModel;
-} ? Row<T> : undefined;
+} ? Row$1<T> : undefined;
 interface RouteContext<P extends string, S extends ObjectShape, A extends boolean, Pl extends boolean = false> {
   /**
    * The app's database at the boundary: each query ends in `.allowed(action)` (the model's policy
@@ -219,6 +233,8 @@ declare class Route<O = unknown> {
   readonly handler: (context: RouteContext<string, ObjectShape, boolean>) => unknown;
   /** Served on the platform's host instead of a tenant's. */
   readonly platform: boolean;
+  /** Checks each upload to its file inputs before it's stored (`upload` in its options). */
+  readonly upload?: UploadCheck | undefined;
   /** Type only: what the handler returns. */
   readonly "~output": O;
   constructor(method: Method, path: string,
@@ -228,7 +244,9 @@ declare class Route<O = unknown> {
    */
   input: ObjectShape | "own", anonymous: boolean, handler: (context: RouteContext<string, ObjectShape, boolean>) => unknown,
   /** Served on the platform's host instead of a tenant's. */
-  platform?: boolean);
+  platform?: boolean,
+  /** Checks each upload to its file inputs before it's stored (`upload` in its options). */
+  upload?: UploadCheck | undefined);
 }
 /** A route that takes no input. */
 type NoInput = Record<never, never>;
@@ -285,6 +303,16 @@ interface TenancyConfig {
 type Named<T> = {
   readonly default: T;
 } & Readonly<Record<string, T>>;
+/** Where a committed write happened, for `onWrite`. */
+interface WriteContext {
+  /** The database's name (`tenant`, `platform`, or the one database's). */
+  readonly database: string;
+  /**
+   * The tenant whose request or service made it (isolated tenancy). None on the platform's
+   * database, nor for what a tenant's database writes as it wakes (the roles from `app.ts`).
+   */
+  readonly tenant?: Row;
+}
 /** The application layer: what `app.ts` returns from `createApp`'s configure callback. */
 interface AppConfig {
   /**
@@ -314,6 +342,14 @@ interface AppConfig {
     readonly language: string;
     readonly timezone: string;
   };
+  /**
+   * Called after every committed write on any of the app's databases, with what it created,
+   * changed and deleted (an `atomic`'s writes in one call): for what has to follow a change outside
+   * the database, such as purging a cache of pages built from it. Rows the database changes
+   * itself (cascade deletes, counts) aren't listed, nor are migrations' writes. It runs before the
+   * write returns; a failure is logged and never fails the write, which is already committed.
+   */
+  readonly onWrite?: (writes: readonly Write[], context: WriteContext) => void | Promise<void>;
   readonly api?: {
     /**
      * Anonymous writes (POST, PUT, PATCH, DELETE with no session) are counted per client IP:
@@ -430,6 +466,13 @@ interface AppFiles {
   }): Promise<string>;
   /** Removes the file (and its sizes) from its storage. */
   delete(file: StoredFile): Promise<void>;
+  /**
+   * Removes the uploads no write attached before their expiry, from storage and the `Upload` table,
+   * in the current database (the tenant's, inside one). Run it from a schedule.
+   */
+  sweep(): Promise<{
+    readonly removed: number;
+  }>;
 }
 //#endregion
 //#region src/tenancy/services.d.ts
@@ -437,6 +480,40 @@ interface AppFiles {
 type AppServices = () => readonly Promise<object>[];
 type Service = (...args: any[]) => unknown;
 //#endregion
+//#region src/tasks/schedule.d.ts
+/**
+ * Schedules: work the app runs on the clock, each a named export of an app module listed in `apps`
+ * (`apps/<name>/tasks.ts`), found like routes.
+ *
+ *   export const nightly = schedule({ daily: "03:00" }, async ({ now }) => { … })
+ *   export const hourly = schedule({ hourly: true }, async () => { … })
+ *
+ * Times are in the app's timezone (`fallbackLocale.timezone`, else UTC), on the hour. The runtime
+ * calls `app.tick(now)` from one hourly timer (on `workers`, the cron line `"0 * * * *"` in
+ * `wrangler.jsonc`), and each tick runs the schedules due in that hour. A tick that's missed is
+ * skipped, never caught up, so a schedule's work is safe to leave to the next time it runs.
+ *
+ * A schedule runs outside any tenant: with isolated tenancy it reaches a tenant through
+ * `app.tenant(id).run(service)`, and the platform through `app.platform.db`.
+ */
+/** When a schedule runs: every hour, or once a day at a whole hour (`"03:00"`). */
+type When = {
+  readonly hourly: true;
+} | {
+  readonly daily: `${number}:00`;
+};
+interface ScheduleContext {
+  /** The tick's time: the hour it's for. */
+  readonly now: Date;
+}
+declare class Schedule {
+  readonly when: When;
+  readonly run: (context: ScheduleContext) => unknown;
+  constructor(when: When, run: (context: ScheduleContext) => unknown);
+}
+/** `schedule(when, run)` in `#app`. */
+declare function schedule(when: When, run: (context: ScheduleContext) => unknown): Schedule;
+//#endregion
 //#region src/app/create-app.d.ts
 /**
  * The app instance services import from `#app`. It's usable at module scope; what it
@@ -468,7 +545,7 @@ interface App {
 }
 interface AppOptions {
   /**
-   * Every `apps/<name>/routes.ts` and `resources.ts`, each as a lazy import, like Django's
+   * Every `apps/<name>/routes.ts`, `resources.ts` and `tasks.ts`, each as a lazy import, like Django's
    * INSTALLED_APPS. Lazy, because those modules import `#app` themselves.
    */
   readonly apps?: AppModules;
@@ -502,6 +579,8 @@ interface CreatedApp<Served, TenantHost = undefined> {
   /** `resource(Model, options)`: what the API exposes over a model. */
   readonly resource: typeof resource;
   readonly fail: typeof fail;
+  /** `schedule({ daily: "03:00" }, run)`: work on the clock, exported from an app module. */
+  readonly schedule: typeof schedule;
 }
 /**
  * `configure` runs once, the first time the runtime starts the core with an env.
@@ -553,6 +632,11 @@ interface InviteInput {
   /** `"platform"`: the tenant's people can't take the role away. */
   readonly held?: (typeof HELD)[number];
 }
+/** What `auth.revoke` takes: an email, and the key of a role from `app.ts`. */
+interface RevokeInput {
+  readonly email: string;
+  readonly role: string;
+}
 //#endregion
 //#region src/auth/create-auth.d.ts
 type Provider = (typeof PROVIDERS)[number];
@@ -600,6 +684,11 @@ interface AuthConfig {
   /** Every permission key: every policy's actions, and `auth.perms`. */
   permissionKeys(): readonly string[];
 }
+/** `auth.invite` and `auth.revoke`, on the app's current database: the core's to attach. */
+interface AuthPeople {
+  invite(input: InviteInput): Promise<void>;
+  revoke(input: RevokeInput): Promise<void>;
+}
 declare class Auth<Env = unknown> {
   private readonly define;
   readonly perms: {
@@ -612,8 +701,8 @@ declare class Auth<Env = unknown> {
   };
   /** The policies made with this instance's `policy()`. */
   readonly policies: PolicyRegistry;
-  /** Set by the app's core when it starts: `invite` on its current database. */
-  private invites;
+  /** Set by the app's core when it starts: `invite` and `revoke` on its current database. */
+  private people;
   constructor(define: (env: Env) => AuthDefinition);
   /**
    * Gives `email` a role from `app.ts`, from code (a tenant's setup service, a seed): now, if it has
@@ -621,8 +710,13 @@ declare class Auth<Env = unknown> {
    * `held: "platform"` puts the assignment beyond the tenant's reach.
    */
   invite(input: InviteInput): Promise<void>;
-  /** The core's: where `invite` writes. */
-  attach(invites: (input: InviteInput) => Promise<void>): void;
+  /**
+   * Takes a role from `email`, from code (replacing a tenant's owner): its invite to the role is
+   * deleted, and the role taken away if it has an account in the current database. Safe to repeat.
+   */
+  revoke(input: RevokeInput): Promise<void>;
+  /** The core's: where `invite` and `revoke` write. */
+  attach(people: AuthPeople): void;
   /** The config, for this env. Checked here for itself; against the databases by the core. */
   resolve(env: Env): AuthConfig;
 }
@@ -648,4 +742,4 @@ interface CreatedAuth<Env> {
 /** The auth instance, from `auth.ts`, with `policy()` and the placeholders policies are written with. */
 declare function createAuth<Env = unknown>(define: (env: Env) => AuthDefinition): CreatedAuth<Env>;
 //#endregion
-export { Permissions as A, Params as C, RouteHandler as D, RouteContext as E, Policy as F, Rules as I, StandardAction as L, Bound as M, DefinePolicy as N, RouteOptions as O, Perms as P, Rejected as R, Method as S, RouteBuilder as T, CustomAction as _, OAuthMethod as a, AppConfig as b, Roles as c, NotImplementedError as d, AppModules as f, createApp as g, CreatedApp as h, Methods as i, AnyPolicy as j, User as k, SignInMethod as l, AppOptions as m, AuthConfig as n, Provider as o, App as p, AuthDefinition as r, RoleDefinition as s, Auth as t, createAuth as u, Resource as v, Route as w, Named as x, ResourceOptions as y, fail as z };
+export { RouteContext as A, Rules as B, AppConfig as C, Params as D, Method as E, AnyPolicy as F, Rejected as H, Bound as I, DefinePolicy as L, RouteOptions as M, User as N, Route as O, Permissions as P, Perms as R, ResourceOptions as S, WriteContext as T, fail as U, StandardAction as V, Schedule as _, OAuthMethod as a, CustomAction as b, Roles as c, NotImplementedError as d, AppModules as f, createApp as g, CreatedApp as h, Methods as i, RouteHandler as j, RouteBuilder as k, SignInMethod as l, AppOptions as m, AuthConfig as n, Provider as o, App as p, AuthDefinition as r, RoleDefinition as s, Auth as t, createAuth as u, ScheduleContext as v, Named as w, Resource as x, When as y, Policy as z };

package/dist/{index-CYcklQ1l.d.ts → index-CaR3hb0i.d.ts}

@@ -222,6 +222,8 @@ declare function file(options?: FileOptions & {
 declare function image(options?: FileOptions & {
   readonly types?: readonly ImageType[];
 }): Kind<StoredFile>;
+/** A PDF or an image to print or read whole (never resized), up to 100 MB. */
+declare function document(options?: FileOptions): Kind<StoredFile>;
 /** Up to 10 files. */
 declare const files: (options?: FileOptions & {
   readonly types?: readonly FileType[];
@@ -230,6 +232,8 @@ declare const files: (options?: FileOptions & {
 declare const images: (options?: FileOptions & {
   readonly types?: readonly ImageType[];
 }) => Kind<StoredFile[], StoredFile[], false, false>;
+/** Up to 100 documents (PDFs and images, each up to 100 MB). */
+declare const documents: (options?: FileOptions) => Kind<StoredFile[], StoredFile[], false, false>;
 //#endregion
 //#region src/validation/kinds/phone.d.ts
 /**
@@ -382,4 +386,4 @@ declare const email: () => Kind<string, string, false, false>;
 /** An http(s) URL, up to 2,048 characters. */
 declare const url: () => Kind<string, string, false, false>;
 //#endregion
-export { images as $, validate as A, money as B, ObjectShape as C, object as D, list as E, datetime as F, FileType as G, sequence as H, fakeUlid as I, SIZES_MAX as J, ImageSize as K, flag as L, IdInput as M, choice as N, serialize as O, date as P, image as Q, id as R, LIST_MAX as S, Shape as T, phone as U, quantity as V, phoneKind as W, file as X, StoredFile as Y, files as Z, define as _, newToken as a, KindSpec as at, CarriesKind as b, slug as c, Sensitivity as ct, text as d, StandardIssue as dt, Fake as et, textKind as f, StandardProps as ft, KindDefinition as g, Definable as h, markdown as i, Kind as it, CalendarDate as j, toKind as k, slugify as l, TypeText as lt, url as m, StandardSchemaV1 as mt, host as n, AnyKind as nt, personName as o, KindTypes as ot, token as p, StandardResult as pt, ImageType as q, line as r, FileSpec as rt, secret as s, Measure as st, email as t, FakeContext as tt, subdomain as u, kind as ut, json as v, Output as w, Input as x, urls as y, int as z };
+export { files as $, validate as A, money as B, ObjectShape as C, object as D, list as E, datetime as F, FileType as G, sequence as H, fakeUlid as I, SIZES_MAX as J, ImageSize as K, flag as L, IdInput as M, choice as N, serialize as O, date as P, file as Q, id as R, LIST_MAX as S, Shape as T, phone as U, quantity as V, phoneKind as W, document as X, StoredFile as Y, documents as Z, define as _, newToken as a, FileSpec as at, CarriesKind as b, slug as c, KindTypes as ct, text as d, TypeText as dt, image as et, textKind as f, kind as ft, KindDefinition as g, StandardSchemaV1 as gt, Definable as h, StandardResult as ht, markdown as i, AnyKind as it, CalendarDate as j, toKind as k, slugify as l, Measure as lt, url as m, StandardProps as mt, host as n, Fake as nt, personName as o, Kind as ot, token as p, StandardIssue as pt, ImageType as q, line as r, FakeContext as rt, secret as s, KindSpec as st, email as t, images as tt, subdomain as u, Sensitivity as ut, json as v, Output as w, Input as x, urls as y, int as z };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 import { p as Runtime, t as AppCore } from "./index-Ce5p2-EB.js";
-import { C as Params, D as RouteHandler, E as RouteContext, O as RouteOptions, R as Rejected, S as Method, T as RouteBuilder, _ as CustomAction, b as AppConfig, d as NotImplementedError, f as AppModules, g as createApp, h as CreatedApp, k as User, m as AppOptions, p as App, v as Resource, w as Route, x as Named, y as ResourceOptions, z as fail } from "./index-D0FEnMhn.js";
-export { type App, type AppConfig, type AppCore, type AppModules, type AppOptions, type CreatedApp, type CustomAction, type Method, type Named, NotImplementedError, type Params, Rejected, type Resource, type ResourceOptions, Route, type RouteBuilder, type RouteContext, type RouteHandler, type RouteOptions, type Runtime, type User, createApp, fail };
+import { A as RouteContext, C as AppConfig, D as Params, E as Method, H as Rejected, M as RouteOptions, N as User, O as Route, S as ResourceOptions, T as WriteContext, U as fail, _ as Schedule, b as CustomAction, d as NotImplementedError, f as AppModules, g as createApp, h as CreatedApp, j as RouteHandler, k as RouteBuilder, m as AppOptions, p as App, v as ScheduleContext, w as Named, x as Resource, y as When } from "./index-Bb9Px6SR.js";
+export { type App, type AppConfig, type AppCore, type AppModules, type AppOptions, type CreatedApp, type CustomAction, type Method, type Named, NotImplementedError, type Params, Rejected, type Resource, type ResourceOptions, Route, type RouteBuilder, type RouteContext, type RouteHandler, type RouteOptions, type Runtime, Schedule, type ScheduleContext, type User, type When, type WriteContext, createApp, fail };