eraspace 0.2.0 → 0.3.0

package/sdk/src/server/index.ts

@@ -151,8 +151,24 @@ export interface TableDefinition<F extends FieldMap = FieldMap, I extends IndexM
     name: N,
     fields: Fs,
   ): TableDefinition<F, Simplify<I & { [P in N]: Fs }>>;
+  /**
+   * Upgrade rows written before this migration to the table's current fields. Versions start at any positive
+   * number and each call takes the next one; rows are written at the last version. A deploy then accepts rows of
+   * an older shape: they are upgraded when read and rewritten in the background. `upgrade` receives the stored
+   * row with `id` and `createdAt` and must return the new row synchronously, depending only on the row.
+   * Undeclared fields of the result are dropped. Keep a migration until every row has passed it.
+   */
+  migrate(version: number, upgrade: (row: StoredRow<F>) => MigratedRow<F>): TableDefinition<F, I>;
 }
 
+/**
+ * A row as an earlier deployment stored it: `id`, `createdAt` and whatever fields it had then. Their types are
+ * unknown, and fields of the current schema may be absent, so they read as `any`.
+ */
+export type StoredRow<F extends FieldMap = FieldMap> = { id: string; createdAt: number } & { [K in keyof F]: any } & { [field: string]: any };
+/** What a migration returns: the row with the table's current fields. `id` and `createdAt` keep their values. */
+export type MigratedRow<F extends FieldMap> = InferInsert<F> & { id?: string; createdAt?: number };
+
 export type AnyTable = TableDefinition<any, any>;
 export type Schema = Record<string, AnyTable>;
 /** The schema a capsule gets when it declares none. Tables and fields are untyped. */
@@ -160,6 +176,7 @@ export type DefaultSchema = Record<string, TableDefinition<Record<string, Field<
 
 export function table<const F extends FieldMap>(fields: F): TableDefinition<F, {}> {
   const indexes: Record<string, readonly string[]> = {};
+  const migrations: number[] = [];
   const def: any = {
     kind: "table",
     fields,
@@ -169,10 +186,20 @@ export function table<const F extends FieldMap>(fields: F): TableDefinition<F, {
       indexes[name] = idx;
       return def;
     },
+    migrate(version: number, upgrade: unknown) {
+      if (!Number.isInteger(version) || version < 1) throw new TypeError("migrate() expects a positive integer version");
+      if (typeof upgrade !== "function") throw new TypeError("migrate() expects a function from a stored row to the upgraded row");
+      const last = migrations.length ? migrations[migrations.length - 1]! : version - 1;
+      if (version !== last + 1) throw new Error(`migrate(${version}) must follow migrate(${last}) with the next version, ${last + 1}`);
+      migrations.push(version);
+      return def;
+    },
     toJSON() {
+      const versions = migrations.length ? { version: migrations[migrations.length - 1], migratesFrom: migrations[0]! - 1 } : {};
       return {
         fields: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, describeField(v)])),
         indexes,
+        ...versions,
       };
     },
   };
@@ -349,6 +376,16 @@ interface BaseContext {
 interface DbHolder<Db> extends BaseContext {
   db: Db;
 }
+export interface Scheduler {
+  /**
+   * Runs mutation `name` with `args` once, `delayMs` milliseconds after this mutation commits. The job commits with
+   * this mutation, so it exists only if this mutation does, and its run commits at most once. Returns the job's id.
+   */
+  runAfter(delayMs: number, name: string, ...args: any[]): string;
+}
+interface MutationHolder<Db> extends DbHolder<Db> {
+  scheduler: Scheduler;
+}
 interface ActionHolder<Db> extends DbHolder<Db> {
   runQuery(name: string, ...args: any[]): Promise<any>;
   runMutation(name: string, ...args: any[]): Promise<any>;
@@ -357,8 +394,8 @@ interface ActionHolder<Db> extends DbHolder<Db> {
 
 /** The `ctx` a `query()` (or a `readOnly` endpoint) receives. */
 export type QueryServerContext<S extends Schema = DefaultSchema> = DbHolder<DbContext<S>>;
-/** The `ctx` a `mutation()` or writable `endpoint()` receives. Its `db` can write. */
-export type ServerContext<S extends Schema = DefaultSchema> = DbHolder<MutationDbContext<S>>;
+/** The `ctx` a `mutation()` or writable `endpoint()` receives. Its `db` can write and its `scheduler` schedules mutations. */
+export type ServerContext<S extends Schema = DefaultSchema> = MutationHolder<MutationDbContext<S>>;
 /** The `ctx` an `action()` receives: read-only db plus `runQuery`/`runMutation`. Use global `fetch` for HTTP. */
 export type ActionServerContext<S extends Schema = DefaultSchema> = ActionHolder<DbContext<S>>;
 
@@ -477,6 +514,8 @@ export interface EndpointRequest {
   json<T = unknown>(): Promise<T>;
   /** Request body bytes as a JSON-compatible number array. */
   bytes(): Promise<number[]>;
+  /** A multipart/form-data or application/x-www-form-urlencoded body. Other content types reject with a TypeError. */
+  formData(): Promise<FormData>;
 }
 
 export interface EndpointResponseOptions {

package/templates/chat/client/index.tsx

@@ -1,7 +1,7 @@
 import { createClient, FilePreview, FileUpload, type FileRef } from "eraspace/client";
 import { useState, useEffect } from "preact/hooks";
 import type app from "../server/index";
-const client = createClient<typeof app>({ reloadOnDeploy: true });
+const client = createClient<typeof app>();
 export default function App() {
   const [room, setRoom] = useState("general");
   const [author, setAuthor] = useState("Guest");

package/templates/poll/client/index.tsx

@@ -1,7 +1,7 @@
 import { createClient } from "eraspace/client";
 import { useState } from "preact/hooks";
 import type app from "../server/index";
-const client = createClient<typeof app>({ reloadOnDeploy: true });
+const client = createClient<typeof app>();
 export default function App() {
   const options = client.useQuery("results");
   const add = client.useMutation("addOption");

package/templates/todo/client/index.tsx

@@ -1,7 +1,7 @@
 import { createClient } from "eraspace/client";
 import { useState } from "preact/hooks";
 import type app from "../server/index";
-const client = createClient<typeof app>({ reloadOnDeploy: true });
+const client = createClient<typeof app>();
 export default function App() {
   const todos = client.useQuery("list");
   const [title, setTitle] = useState("");