eraspace 0.1.0 → 0.3.0

package/sdk/src/client/types.ts

@@ -1,6 +1,7 @@
 import type { ReadonlySignal } from "@preact/signals";
 import type { EraspaceError } from "./errors.ts";
 import type { StorageClient } from "./storage.ts";
+import type { Upload, UseUploadOptions } from "./files.ts";
 
 import type {
   ActionArgs,
@@ -72,11 +73,15 @@ export interface Room<M = Record<string, unknown>, S extends Record<string, unkn
   on(event: string, cb: (payload: any, from: string | undefined) => void): () => void;
   /** Ephemeral shared state (kept by the room process, never stored). */
   state: Partial<S>;
+  /** Last room join or write error. Cleared by a successful join or state update. */
+  error: EraspaceError | undefined;
   setState<K extends keyof S & string>(key: K, value: S[K]): void;
 }
 
 export interface EraspaceClient<C> {
   readonly storage: StorageClient;
+  /** Upload files to app storage with progress and errors as component state. `<FileUpload>` wraps this. */
+  useUpload(options?: UseUploadOptions): Upload;
   /** Subscribe to a query. Returns `undefined` until the first result arrives, then live values. */
   useQuery<N extends QueryName<C>>(name: N, ...args: QueryArgs<C, N>): QueryResult<C, N> | undefined;
   /** Pass computed signals directly to JSX text nodes for updates without a component render. */
@@ -102,6 +107,8 @@ export interface EraspaceClient<C> {
 
   query<N extends QueryName<C>>(name: N, ...args: QueryArgs<C, N>): Promise<QueryResult<C, N>>;
   mutation<N extends MutationName<C>>(name: N, ...args: MutationArgs<C, N>): Promise<MutationResult<C, N>>;
+  /** Recover an unknown mutation outcome with its original name, arguments and request key, within 24 hours. */
+  retryMutation<N extends MutationName<C>>(name: N, args: MutationArgs<C, N>, requestKey: string): Promise<MutationResult<C, N>>;
   action<N extends ActionName<C>>(name: N, ...args: ActionArgs<C, N>): Promise<ActionResult<C, N>>;
   /** Imperative live subscription. Returns an unsubscribe function. */
   subscribe<N extends QueryName<C>>(

package/sdk/src/server/index.ts

@@ -1,9 +1,8 @@
 // Generated by scripts/generate-server-api.ts. Edit api/server-api.ts or api/server.ts.in.
 // eraspace/server: capsule definition API.
 //
-// On the platform this module is never executed. The compiler maps `eraspace/server` to the Erlang module
-// `sbrt_sdk`, which implements the same constructors. The implementations below are thin descriptors so that the
-// module also works in Bun (tests, tooling) and, mainly, so the types drive inference.
+// V8 supplies this module from the engine bootstrap. These descriptors also run in Node for tooling and tests;
+// their types drive client and server inference.
 //
 // Type design. `ctx.db` must be typed from `schema` even though both live in the same object literal:
 //
@@ -152,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. */
@@ -161,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,
@@ -170,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,
       };
     },
   };
@@ -350,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>;
@@ -358,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>>;
 
@@ -476,8 +512,10 @@ export interface EndpointRequest {
   query: EndpointQuery;
   text(): Promise<string>;
   json<T = unknown>(): Promise<T>;
-  /** Request body bytes. Typed arrays are not supported by the runtime. */
+  /** 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 } from "eraspace/client";
+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");
@@ -9,6 +9,7 @@ export default function App() {
   const [error, setError] = useState("");
   const [sending, setSending] = useState(false);
   const [typing, setTyping] = useState("");
+  const [file, setFile] = useState<FileRef | null>(null);
   const messages = client.useQuery("messages", room);
   const send = client.useMutation("send");
   const channel = client.useRoom<{ name: string }> (room, { name: author });
@@ -22,14 +23,17 @@ export default function App() {
       <input name="room" aria-label="Room" defaultValue={room} maxLength={40}/><button class="subtle">Join room</button>
     </form>
     <div class="presence">{channel.presence.length} online · {channel.presence.map(member => member.meta.name || "Guest").join(", ")}</div>
-    {messages === undefined ? <p>Loading messages…</p> : messages.length === 0 ? <p>Send the first message.</p> : <ul>{[...messages].reverse().map(message => <li key={message.id}><strong>{message.author}</strong><span>{message.body}</span><time>{new Date(message.createdAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</time></li>)}</ul>}
+    {messages === undefined ? <p>Loading messages…</p> : messages.length === 0 ? <p>Send the first message.</p> : <ul>{[...messages].reverse().map(message => <li key={message.id}><strong>{message.author}</strong><span>{message.body}{message.file && <FilePreview client={client} file={message.file} class="attachment"/>}</span><time>{new Date(message.createdAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</time></li>)}</ul>}
     <form onSubmit={async e => {
       e.preventDefault(); setSending(true); setError("");
-      try { await send(room, author, body); setBody(""); } catch (err) { setError(err instanceof Error ? err.message : String(err)); } finally { setSending(false); }
+      try { await send(room, author, body, file); setBody(""); setFile(null); } catch (err) { setError(err instanceof Error ? err.message : String(err)); } finally { setSending(false); }
     }}>
       <input aria-label="Your name" value={author} maxLength={40} onInput={e => setAuthor(e.currentTarget.value)}/>
-      <input aria-label="Message" placeholder="Message" value={body} maxLength={2000} required onInput={e => { setBody(e.currentTarget.value); channel.broadcast("typing", author); }}/>
-      <button disabled={sending || !body.trim()}>Send</button>
+      <input aria-label="Message" placeholder="Message" value={body} maxLength={2000} required={!file} onInput={e => { setBody(e.currentTarget.value); channel.broadcast("typing", author); }}/>
+      <button disabled={sending || (!body.trim() && !file)}>Send</button>
+      {file
+        ? <div class="pending"><FilePreview client={client} file={file} caption={false} class="attachment"/><span>{file.name}</span><button type="button" class="subtle" disabled={sending} onClick={() => { void client.storage.delete(file.key).catch(() => {}); setFile(null); }}>Remove</button></div>
+        : <FileUpload client={client} class="attach" onUpload={setFile}>Attach a file (up to 5 MB)</FileUpload>}
     </form>
     {typing && <small>{typing} is typing</small>}
     {error && <p role="alert">{error}</p>}

package/templates/chat/client/styles.css

@@ -24,5 +24,20 @@
   meter::-moz-meter-bar { background: #fff; }
   .done { text-decoration: line-through; }
   .presence { padding: 12px 0; font-size: 13px; }
+  .attach { flex-basis: 100%; padding: 10px; border: 1px dashed #666; color: #aaa; font-size: 13px; text-align: center; cursor: pointer; position: relative; }
+  .attach[data-dragging], .attach:hover, .attach:focus-within { border-color: #fff; color: #fff; }
+  .attach progress { display: block; width: 100%; margin-top: 6px; accent-color: #fff; }
+  .pending { flex-basis: 100%; display: flex; align-items: center; gap: 12px; font-size: 13px; }
+  .pending > span { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  li:has(.attachment) { align-items: flex-start; }
+  .attachment { margin: 8px 0 0; }
+  li > span > .attachment:first-child { margin-top: 0; }
+  .attachment img, .attachment video { display: block; max-width: 100%; max-height: 280px; border: 1px solid #333; }
+  .pending .attachment { margin: 0; }
+  .pending .attachment img { max-height: 48px; }
+  .attachment audio { display: block; width: 100%; }
+  .attachment iframe { display: block; width: 100%; height: 160px; border: 1px solid #333; background: #fff; }
+  .attachment a { color: #ccc; display: inline-flex; gap: 8px; }
+  .attachment figcaption { display: flex; gap: 8px; margin-top: 4px; font-size: 12px; color: #888; }
   @media (max-width: 480px) { main { padding: 20px 12px; } li { flex-wrap: wrap; } }
 }

package/templates/chat/server/index.ts

@@ -1,17 +1,27 @@
-import { capsule, table, query, mutation, endpoint, string, text } from "eraspace/server";
+import { capsule, table, query, mutation, endpoint, string, number, object, text } from "eraspace/server";
+type Attachment = { key: string; name: string; contentType: string; size: number };
+const KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 export default capsule({
-  schema: { messages: table({ room: string(), author: string(), body: string() }).index("by_room", ["room"]) },
+  schema: {
+    messages: table({
+      room: string(), author: string(), body: string(),
+      // A file in app storage, saved from the client's FileUpload.
+      file: object({ key: string(), name: string(), contentType: string(), size: number() }).optional(),
+    }).index("by_room", ["room"]),
+  },
   queries: {
     messages: query(async (ctx, room: string) => ctx.db.messages.withIndex("by_room", q => q.eq("room", room)).order("desc").take(100)),
   },
   mutations: {
-    send: mutation(async (ctx, room: string, author: string, body: string) => {
+    send: mutation(async (ctx, room: string, author: string, body: string, file?: Attachment | null) => {
       const trimmed = body.trim();
-      if (!trimmed || trimmed.length > 2000) throw new Error("Write a message of 1 to 2000 characters.");
+      if (trimmed.length > 2000 || (!trimmed && !file)) throw new Error("Write a message of 1 to 2000 characters.");
+      if (file && (!KEY.test(String(file.key)) || typeof file.name !== "string" || typeof file.contentType !== "string" || !Number.isInteger(file.size) || file.size < 0)) throw new Error("That attachment is not a stored file.");
       const name = author.trim().slice(0, 40) || "Guest";
       ctx.log.info("message sent", { room });
-      return ctx.db.messages.insert({ room, author: name, body: trimmed });
+      const attachment = file ? { key: file.key, name: file.name.slice(0, 255) || "file", contentType: file.contentType.slice(0, 256), size: file.size } : undefined;
+      return ctx.db.messages.insert({ room, author: name, body: trimmed, file: attachment });
     }),
   },
-  endpoints: { hi: endpoint({ method: "GET", path: "/hi", readOnly: true }, () => text("hello from BEAM")) },
+  endpoints: { hi: endpoint({ method: "GET", path: "/hi", readOnly: true }, () => text("hello from eraspace")) },
 });

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("");