lowlander 0.2.2 → 0.2.4

package/skill/SKILL.md

@@ -134,6 +134,24 @@ export function streamPerson(name: string) {
 
 On the client, this returns a reactive Aberdeen proxy that updates live when server data changes.
 
+```ts
+// Client-side
+const person = api.streamPerson('Alice');
+// person.value starts as undefined while loading, and
+// then becomes a live-updating reactive proxy object of Alice's data
+A.dump(person);
+```
+
+Lowlander will keep `person.value` up-to-date as long as the Aberdeen scope containing `api.streamPerson` remains active. When the scope is destroyed, the stream subscription is automatically cancelled.
+
+It's quite common for the same RPC call to be used to get the same stream multiple times in a short period; when navigating back and forth, or when navigating to a new page that requires some of the same data as the previous page. To optimize for this, `createStreamType` accepts an optional `cache` parameter (in seconds). 
+
+```ts
+const PersonStream = createStreamType(Person, fields, { cache: 30 }); // cache for 30s after going out of scope
+```
+
+After a stream with caching goes out of scope, the server keeps it alive for that many seconds, so that if the same stream is requested again with the same parameters, it can be reused instantly without re-sending initial data or re-subscribing to updates. Cached stream rpcs also deduplicate within that time window, so if the same stream is requested multiple times while it's still active or cached, only one stream is created on the server and shared among all requests.
+
 ### ServerProxy for Stateful APIs
 
 Wrap a class instance to expose per-connection stateful methods:
@@ -285,90 +303,29 @@ Set `EDINBURGH_LOG_LEVEL` similarly for Edinburgh internals.
 
 The following is auto-generated from `server/server.ts`:
 
-### createStreamType · function
+### [createStreamType](createStreamType.md) · function
 
 Creates a stream type for reactive model streaming to clients with automatic updates.
 
-Specify which fields to include; when they change, updates are pushed to subscribed clients.
-Supports nested linked models and type-safe field selection.
-
-**Signature:** `<T, S extends FieldSelection<T>>(Model: typeof E.Model<unknown> & (new (...args: any[]) => T), selection: S & ValidateSelection<T, S>) => typeof StreamType`
-
-**Type Parameters:**
-
-- `T`
-- `S extends FieldSelection<T>`
-
-**Parameters:**
-
-- `Model: ModelClass & (new (...args: any[]) => T)` - - The Edinburgh model class
-- `selection: S & ValidateSelection<T, S>` - - Field selection: `true` for simple fields, nested object for linked models
-
-**Returns:** Stream type class to instantiate in API functions
-
-**Examples:**
-
-```ts
-
-### sendModel · function
+### [sendModel](sendModel.md) · function
 
 Sends (updated) data for `model` to `target`.
 `target` is a virtual socket with a requestId+'d' user prefix, or a channel that subscribes such virtual sockets.
 
-**Signature:** `(target: number | Uint8Array<ArrayBufferLike> | number[], model: Model<any>, commitId: number, StreamType: typeof StreamTypeBase<any>, changed?: Change) => void`
-
-**Parameters:**
-
-- `target: Uint8Array | number | number[]`
-- `model: E.Model<any>`
-- `commitId: number`
-- `StreamType: typeof StreamTypeBase<any>`
-- `changed?: E.Change`
-
-### pushModel · function
+### [pushModel](pushModel.md) · function
 
 Subscribes `target` to this model, and sends initial data.
 `target` is a virtual socket with a requestId+'d' user prefix, or a channel that subscribes such virtual sockets.
 
-**Signature:** `(target: number | Uint8Array<ArrayBufferLike> | number[], model: Model<any>, commitId: number, SubStreamType: typeof StreamTypeBase<any>, delta: number) => void`
-
-**Parameters:**
-
-- `target: number | Uint8Array | number[]`
-- `model: E.Model<any>`
-- `commitId: number`
-- `SubStreamType: typeof StreamTypeBase<any>`
-- `delta: number`
-
-### start · function
+### [start](start.md) · function
 
 Starts the Lowlander WebSocket server.
 
-**Signature:** `(mainApiFile: string, opts?: { bind?: string; threads?: number; injectWarpSocket?: typeof import("/var/home/frank/projects/lowlander/node_modules/warpsocket/dist/src/index", { with: { "resolution-mode": "import" } }); }) => Promise<void>`
-
-**Parameters:**
-
-- `mainApiFile: string` - - Absolute path to the compiled API file exporting server functions
-- `opts: {bind?: string, threads?: number, injectWarpSocket?: typeof realWarpsocket}` (optional)
-
-**Examples:**
-
-```ts
-import { start } from 'lowlander/server';
-import { fileURLToPath } from 'url';
-import { resolve, dirname } from 'path';
-
-const API_FILE = resolve(dirname(fileURLToPath(import.meta.url)), 'api.js');
-start(API_FILE, { bind: '0.0.0.0:8080' });
-```
-
 ### logLevel · constant
 
 **Value:** `number`
 
-### warpsocket · class
-
-**Type:** `typeof import("/var/home/frank/projects/lowlander/node_modules/warpsocket/dist/src/index", { with: { "resolution-mode": "import" } })`
+### [warpsocket](warpsocket.md) · class
 
 ### StreamTypeBase · abstract class
 
@@ -386,118 +343,55 @@ start(API_FILE, { bind: '0.0.0.0:8080' });
 
 **Type:** `number`
 
-#### streamTypeBase.toString · method
+#### StreamTypeBase.cache · static property
 
-**Signature:** `() => string`
+**Type:** `number`
 
-**Parameters:**
+#### streamTypeBase.toString · method
 
+**Signature:** `() => string`
 
-### ServerProxy · class
+### [ServerProxy](ServerProxy.md) · class
 
 Wraps a server-side API object to create a stateful, type-safe proxy accessible from clients.
 Use for authentication, sessions, or any stateful context that persists across RPC calls.
 
-**Type Parameters:**
-
-- `API extends object`
-- `RETURN`
-
-**Examples:**
-
-```ts
-export class UserAPI {
-  constructor(public user: User) {}
-  getSecret() { return this.user.secret; }
-}
-
-export async function authenticate(token: string) {
-  const user = await validateToken(token);
-  return new ServerProxy(new UserAPI(user), user.name);
-}
-
-// Client: auth.value is user name, auth.serverProxy.getSecret() calls UserAPI method
-```
-
-**Constructor Parameters:**
-
-- `api`: - Server-side API object exposed to the client
-- `value`: - Value returned immediately to the client
-
 #### serverProxy.toString · method
 
 **Signature:** `() => string`
 
-**Parameters:**
-
-
-### Socket · class
+### [Socket](Socket.md) · class
 
 Server-side socket for pushing data to a client. Server functions with `Socket<T>` parameters
 receive client callbacks on the client side.
 
-**Type Parameters:**
-
-- `T`
-
-**Examples:**
-
-```ts
-// Server
-export function streamNumbers(socket: Socket<number>) {
-  setInterval(() => {
-    if (!socket.send(Math.random())) clearInterval(interval);
-  }, 1000);
-}
-
-// Client
-api.streamNumbers(num => console.log(num));
-```
-
-#### socket.send · method
+#### [socket.send](Socket_send.md) · method
 
 Sends data to the client.
 
-**Signature:** `(data: T) => number`
-
-**Parameters:**
-
-- `data: T` - - Data to send (automatically serialized)
-
-**Returns:** `true` if sent, `false` if socket is closed
-
-#### socket.subscribe · method
-
-**Signature:** `(channel: Uint8Array<ArrayBufferLike>, delta?: number) => void`
-
-**Parameters:**
-
-- `channel: Uint8Array`
-- `delta: any` (optional)
+#### [socket.subscribe](Socket_subscribe.md) · method
 
 #### socket.toString · method
 
 **Signature:** `() => string`
 
-**Parameters:**
-
-
 #### socket.[Symbol.for('nodejs.util.inspect.custom')] · method
 
 **Signature:** `() => string`
 
-**Parameters:**
-
-
 ## Client API Reference
 
 The following is auto-generated from `client/client.ts`:
 
-### logLevel · variable
+### setLogLevel · function
 
-Set to 1-3 for increasing verbosity.
+Set to 0-3 for increasing verbosity.
 
-**Value:** `number`
+**Signature:** `(level: number) => void`
+
+**Parameters:**
+
+- `level: number`
 
 ### ClientProxyObject · type
 
@@ -507,42 +401,11 @@ Transforms server-side API objects to client-side proxy objects with type-safe R
     [K in keyof T]: ClientProxyFunction<T[K]>
 }`
 
-### Connection · class
+### [Connection](Connection.md) · class
 
 WebSocket connection to a Lowlander server with type-safe RPC, automatic reconnection,
 and reactive updates.
 
-**Type Parameters:**
-
-- `T`
-
-**Examples:**
-
-```ts
-import type * as API from './server/api.js';
-const conn = new Connection<typeof API>('ws://localhost:8080/');
-
-// Simple RPC - returns PromiseProxy
-const sum = conn.api.add(1, 2);
-
-// Server proxy for stateful APIs
-const auth = conn.api.authenticate('token');
-const secret = auth.serverProxy.getSecret();
-
-// Streaming with callbacks
-conn.api.streamData(data => console.log(data));
-
-// Use within Aberdeen reactive scopes
-$(() => {
-  dump(conn.isOnline());
-  dump(sum);
-});
-```
-
-**Constructor Parameters:**
-
-- `url`: - WebSocket URL (e.g., 'ws://localhost:8080/'), or a fake WebSocket object for testing
-
 #### connection.ws · property
 
 **Type:** `WebSocket`
@@ -563,6 +426,10 @@ $(() => {
 
 **Type:** `ValueRef<boolean>`
 
+#### connection.streamCache · property
+
+**Type:** `Map<string, StreamCacheEntry>`
+
 #### connection.api · property
 
 Type-safe proxy to the server-side API. Methods return `PromiseProxy` objects
@@ -577,29 +444,29 @@ Returns the current connection status. Reactive in Aberdeen scopes.
 
 **Signature:** `() => boolean`
 
-**Parameters:**
-
-
 #### connection.connect · method
 
 **Signature:** `() => void`
 
-**Parameters:**
-
-
 #### connection.reconnect · method
 
 **Signature:** `() => void`
 
+#### [connection.pruneCommitIds](Connection_pruneCommitIds.md) · method
+
+#### connection.cancelRequest · method
+
+**Signature:** `(request: ActiveRequest) => void`
+
 **Parameters:**
 
+- `request: ActiveRequest`
 
-#### connection.pruneCommitIds · method
+#### connection.startLinger · method
 
-**Signature:** `(request: ActiveRequest, maxCommitId: number) => void`
+**Signature:** `(cached: StreamCacheEntry) => void`
 
 **Parameters:**
 
-- `request: ActiveRequest`
-- `maxCommitId: number`
+- `cached: StreamCacheEntry`
 

package/skill/ServerProxy.md

@@ -0,0 +1,30 @@
+### ServerProxy · class
+
+Wraps a server-side API object to create a stateful, type-safe proxy accessible from clients.
+Use for authentication, sessions, or any stateful context that persists across RPC calls.
+
+**Type Parameters:**
+
+- `API extends object`
+- `RETURN`
+
+**Examples:**
+
+```ts
+export class UserAPI {
+  constructor(public user: User) {}
+  getSecret() { return this.user.secret; }
+}
+
+export async function authenticate(token: string) {
+  const user = await validateToken(token);
+  return new ServerProxy(new UserAPI(user), user.name);
+}
+
+// Client: auth.value is user name, auth.serverProxy.getSecret() calls UserAPI method
+```
+
+**Constructor Parameters:**
+
+- `api`: - Server-side API object exposed to the client
+- `value`: - Value returned immediately to the client

package/skill/Socket.md

@@ -0,0 +1,22 @@
+### Socket · class
+
+Server-side socket for pushing data to a client. Server functions with `Socket<T>` parameters
+receive client callbacks on the client side.
+
+**Type Parameters:**
+
+- `T`
+
+**Examples:**
+
+```ts
+// Server
+export function streamNumbers(socket: Socket<number>) {
+  setInterval(() => {
+    if (!socket.send(Math.random())) clearInterval(interval);
+  }, 1000);
+}
+
+// Client
+api.streamNumbers(num => console.log(num));
+```

package/skill/Socket_send.md

@@ -0,0 +1,11 @@
+#### socket.send · method
+
+Sends data to the client.
+
+**Signature:** `(data: T) => number`
+
+**Parameters:**
+
+- `data: T` - - Data to send (automatically serialized)
+
+**Returns:** `true` if sent, `false` if socket is closed

package/skill/Socket_subscribe.md

@@ -0,0 +1,8 @@
+#### socket.subscribe · method
+
+**Signature:** `(channel: Uint8Array<ArrayBufferLike>, delta?: number) => void`
+
+**Parameters:**
+
+- `channel: Uint8Array`
+- `delta: any` (optional)

package/skill/createStreamType.md

@@ -0,0 +1,45 @@
+### createStreamType · function
+
+Creates a stream type for reactive model streaming to clients with automatic updates.
+
+Specify which fields to include; when they change, updates are pushed to subscribed clients.
+Supports nested linked models and type-safe field selection.
+
+**Signature:** `<T, S extends FieldSelection<T>>(Model: typeof E.Model<unknown> & (new (...args: any[]) => T), selection: S & ValidateSelection<T, S>, options?: { cache?: number; }) => typeof StreamType`
+
+**Type Parameters:**
+
+- `T`
+- `S extends FieldSelection<T>`
+
+**Parameters:**
+
+- `Model: ModelClass & (new (...args: any[]) => T)` - - The Edinburgh model class
+- `selection: S & ValidateSelection<T, S>` - - Field selection: `true` for simple fields, nested object for linked models
+- `options?: { cache?: number }` - - Optional settings
+
+**Returns:** Stream type class to instantiate in API functions
+
+**Examples:**
+
+```ts
+⁣@E.registerModel
+class Person extends Model {
+  name = field(string);
+  age = field(number);
+  password = field(string);
+  friends = field(array(link(Person)));
+}
+
+// Exclude password, include friends' names; cache 30s
+const PersonStream = createStreamType(Person, {
+  name: true,
+  age: true,
+  friends: { name: true }
+}, { cache: 30 });
+
+export function streamPerson() {
+  const person = Person.byName.get('Alice')!;
+  return new PersonStream(person);
+}
+```

package/skill/pushModel.md

@@ -0,0 +1,14 @@
+### pushModel · function
+
+Subscribes `target` to this model, and sends initial data.
+`target` is a virtual socket with a requestId+'d' user prefix, or a channel that subscribes such virtual sockets.
+
+**Signature:** `(target: number | Uint8Array<ArrayBufferLike> | number[], model: Model<any>, commitId: number, SubStreamType: typeof StreamTypeBase<any>, delta: number) => void`
+
+**Parameters:**
+
+- `target: number | Uint8Array | number[]`
+- `model: E.Model<any>`
+- `commitId: number`
+- `SubStreamType: typeof StreamTypeBase<any>`
+- `delta: number`

package/skill/sendModel.md

@@ -0,0 +1,14 @@
+### sendModel · function
+
+Sends (updated) data for `model` to `target`.
+`target` is a virtual socket with a requestId+'d' user prefix, or a channel that subscribes such virtual sockets.
+
+**Signature:** `(target: number | Uint8Array<ArrayBufferLike> | number[], model: Model<any>, commitId: number, StreamType: typeof StreamTypeBase<any>, changed?: Change) => void`
+
+**Parameters:**
+
+- `target: Uint8Array | number | number[]`
+- `model: E.Model<any>`
+- `commitId: number`
+- `StreamType: typeof StreamTypeBase<any>`
+- `changed?: E.Change`

package/skill/start.md

@@ -0,0 +1,21 @@
+### start · function
+
+Starts the Lowlander WebSocket server.
+
+**Signature:** `(mainApiFile: string, opts?: { bind?: string; threads?: number; injectWarpSocket?: typeof import("/var/home/frank/projects/warpsocket/dist/src/index", { with: { "resolution-mode": "import" } }); }) => Promise<void>`
+
+**Parameters:**
+
+- `mainApiFile: string` - - Absolute path to the compiled API file exporting server functions
+- `opts: {bind?: string, threads?: number, injectWarpSocket?: typeof realWarpsocket}` (optional)
+
+**Examples:**
+
+```ts
+import { start } from 'lowlander/server';
+import { fileURLToPath } from 'url';
+import { resolve, dirname } from 'path';
+
+const API_FILE = resolve(dirname(fileURLToPath(import.meta.url)), 'api.js');
+start(API_FILE, { bind: '0.0.0.0:8080' });
+```

package/skill/warpsocket.md

@@ -0,0 +1,3 @@
+### warpsocket · class
+
+**Type:** `typeof import("/var/home/frank/projects/warpsocket/dist/src/index", { with: { "resolution-mode": "import" } })`