lowlander 0.2.3 → 0.3.0

package/server/wshandler.ts

@@ -41,7 +41,18 @@ export async function handleBinaryMessage(message: Uint8Array, socketId: number)
         // Delete server proxy object, if any
         const cancelRequestId = pack.readPositiveInt();
         const proxies = socketProxies.get(socketId);
-        if (proxies) proxies.delete(cancelRequestId);
+        if (proxies) {
+            /** Call `onDrop()` on a proxy if it has one. Runs in a transaction; errors are logged. */
+            const proxy = proxies.get(cancelRequestId);
+            proxies.delete(cancelRequestId);
+            if (proxy && typeof proxy.onDrop === 'function') {
+                try {
+                    await E.transact(() => proxy.onDrop());
+                } catch (err: any) {
+                    console.error('cancel request onDrop error', err);
+                }
+            }
+        }
 
         // Delete any virtual sockets created for this request
         for(const virtualSocketId of pack.read() || []) {
@@ -88,20 +99,24 @@ export async function handleBinaryMessage(message: Uint8Array, socketId: number)
         }
 
         try {
-            let pendingSend: (() => void) | undefined;
+            let pendingPacket: Uint8Array | undefined;
             await E.transact(async () => {
                 let response = await func.apply(api, params);
                 if (logLevel >= 2) console.log('[lowlander] Called', methodName, 'with', params, '->', typeof response === 'object' && response ? response.toString() : JSON.stringify(response));
 
-                // Result processing/sending should be within the transaction, as it may involve (lazy) loading models
+                // Result processing/serialization should be within the transaction, as it may involve (lazy) loading models.
+                // The actual socket send remains deferred until after commit.
 
                 if (response instanceof ServerProxy) {
+                    if (response.value instanceof StreamTypeBase) {
+                        throw new Error('ServerProxy values cannot be streamed models; return the stream directly or from a proxy method instead');
+                    }
                     let proxies = socketProxies.get(socketId);
                     if (!proxies) socketProxies.set(socketId, proxies = new Map());
                     if (logLevel >= 3) console.log('[lowlander] Setting proxy id', requestId, 'for socket', socketId);
                     proxies.set(requestId, response.api);
-                    
-                    pendingSend = () => send(socketId, requestId, SERVER_MESSAGES.response_proxy, response.value, virtualSocketIds);
+
+                    pendingPacket = DataPack.createUint8Array(requestId, SERVER_MESSAGES.response_proxy, response.value, virtualSocketIds);
 
                 } else if (response instanceof StreamTypeBase) {
                     const StreamType = response.constructor as typeof StreamTypeBase<any>;
@@ -115,14 +130,15 @@ export async function handleBinaryMessage(message: Uint8Array, socketId: number)
                     pushModel(virtualSocketId, instance, 0, StreamType, 1);
 
                     // Then respond, indicating which row should be top level
-                    pendingSend = () => send(socketId, requestId, SERVER_MESSAGES.response_model, virtualSocketIds, instance.getPrimaryKeyHash() + StreamType.id);
+                    const cacheMs = StreamType.cache !== undefined ? StreamType.cache * 1000 : undefined;
+                    pendingPacket = DataPack.createUint8Array(requestId, SERVER_MESSAGES.response_model, virtualSocketIds, instance.getPrimaryKeyHash() + StreamType.id, cacheMs);
                 } else {
                     // A regular result
-                    pendingSend = () => send(socketId, requestId, SERVER_MESSAGES.response, response, virtualSocketIds);
+                    pendingPacket = DataPack.createUint8Array(requestId, SERVER_MESSAGES.response, response, virtualSocketIds);
                 }
             });
             // Send response after transaction has committed
-            pendingSend!();
+            warpsocket.send(socketId, pendingPacket!);
         } catch (error: any) {
             console.error('RPC error', error);
             sendError(socketId, requestId, error.message || 'Internal error');
@@ -132,7 +148,22 @@ export async function handleBinaryMessage(message: Uint8Array, socketId: number)
     }
 }
 
-export function handleClose(socketId: number) {
+export async function handleClose(socketId: number) {
     if (logLevel >= 1) console.log('[lowlander] Client disconnected', socketId);
+    const proxies = socketProxies.get(socketId);
+    if (!proxies) return;
     socketProxies.delete(socketId);
+    if (!proxies.values().some(p => typeof p.onDrop === 'function')) return;
+    
+    await E.transact(async () => {
+        for (const proxy of proxies.values()) {
+            if (typeof proxy?.onDrop === 'function') {
+                try {
+                    await proxy.onDrop();
+                } catch (err: any) {
+                    console.error('handleClose onDrop error', err);
+                }
+            }
+        }
+    });
 }

package/skill/SKILL.md

@@ -93,14 +93,12 @@ Define persistent data models using Edinburgh. See [Edinburgh docs](https://gith
 ```ts
 import * as E from 'edinburgh';
 
-@E.registerModel
-class Person extends E.Model<Person> {
-    static byName = E.primary(Person, 'name');
+const Person = E.defineModel('Person', class {
     name = E.field(E.string);
     age = E.field(E.number);
-    friends = E.field(E.array(E.link(Person)));
+    friends = E.field(E.array(E.link(() => Person)));
     password = E.field(E.string);
-}
+}, { pk: 'name' });
 ```
 
 Models are ACID, and RPC calls automatically run in transactions. When creating a `new Instance()` or updating props on an existing instance, changes are persisted to disk automatically. `E.link` objects are lazy-loaded.
@@ -127,25 +125,44 @@ Use `true` for plain fields. For linked model fields, provide a nested selection
 
 ```ts
 export function streamPerson(name: string) {
-    const person = Person.byName.get(name)!;
+    const person = Person.getBy('name', name)!;
     return new PersonStream(person);
 }
 ```
 
 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:
 
 ```ts
+// server-side api
 import { ServerProxy } from 'lowlander/server';
 
 class UserAPI {
     constructor(public userName: string) {}
     
     get user(): Person {
-        return Person.byName.get(this.userName)!;
+        return Person.getBy('name', this.userName)!;
     }
 
     getBio() {
@@ -154,7 +171,7 @@ class UserAPI {
 }
 
 export async function authenticate(token: string) {
-    const user = Person.byName.get(token);
+    const user = Person.getBy('name', token);
     if (!user) throw new Error('User not found');
     return new ServerProxy(new UserAPI(token), 'secret-value');
 }
@@ -162,6 +179,14 @@ export async function authenticate(token: string) {
 
 The client receives `'secret-value'` as `.value` and can call `UserAPI` methods via `.serverProxy`.
 
+When a proxy is dropped, because the request's Aberdeen scope was destroyed or the WebSocket disconnected, Lowlander calls `onDrop()` on the API object if it exists, letting you clean up server-side state.
+
+```ts
+// client-side
+const auth = api.authenticate('Alice');
+dump(auth.serverProxy.getBio());
+```
+
 ### Socket Callbacks
 
 Use `Socket<T>` parameters for server-push streaming. On the client, these become callback functions:
@@ -325,6 +350,10 @@ Starts the Lowlander WebSocket server.
 
 **Type:** `number`
 
+#### StreamTypeBase.cache · static property
+
+**Type:** `number`
+
 #### streamTypeBase.toString · method
 
 **Signature:** `() => string`
@@ -404,6 +433,10 @@ and reactive updates.
 
 **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
@@ -428,3 +461,19 @@ Returns the current connection status. Reactive in Aberdeen scopes.
 
 #### [connection.pruneCommitIds](Connection_pruneCommitIds.md) · method
 
+#### connection.cancelRequest · method
+
+**Signature:** `(request: ActiveRequest) => void`
+
+**Parameters:**
+
+- `request: ActiveRequest`
+
+#### connection.startLinger · method
+
+**Signature:** `(cached: StreamCacheEntry) => void`
+
+**Parameters:**
+
+- `cached: StreamCacheEntry`
+

package/skill/ServerProxy.md

@@ -3,6 +3,10 @@
 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.
 
+If the API object has an `onDrop()` method, it is called when the proxy is dropped, either
+because the client cancelled the request (scope cleanup) or the WebSocket disconnected.
+Use this to clean up server-side state kept on behalf of the client.
+
 **Type Parameters:**
 
 - `API extends object`
@@ -14,6 +18,7 @@ Use for authentication, sessions, or any stateful context that persists across R
 export class UserAPI {
   constructor(public user: User) {}
   getSecret() { return this.user.secret; }
+  onDrop() { console.log('client gone'); }
 }
 
 export async function authenticate(token: string) {

package/skill/createStreamType.md

@@ -5,7 +5,7 @@ Creates a stream type for reactive model streaming to clients with automatic upd
 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`
+**Signature:** `<T, S extends FieldSelection<T>>(Model: (new () => any) & ModelClassRuntime<any, readonly any[], any, any> & (new (initial?: Partial<any>, txn?: Transaction) => any) & (new (...args: any[]) => T), selection: S & ValidateSelection<...>, options?: { ...; }) => typeof StreamType`
 
 **Type Parameters:**
 
@@ -14,31 +14,31 @@ Supports nested linked models and type-safe field selection.
 
 **Parameters:**
 
-- `Model: ModelClass & (new (...args: any[]) => T)` - - The Edinburgh model class
+- `Model: E.AnyModelClass & (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
+const Person = E.defineModel('Person', class {
+  name = E.field(E.string);
+  age = E.field(E.number);
+  password = E.field(E.string);
+  friends = E.field(E.array(E.link(() => Person)));
+}, { pk: 'name' });
+
+// 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')!;
+  const person = Person.get('Alice')!;
   return new PersonStream(person);
 }
 ```

package/skill/pushModel.md

@@ -3,7 +3,7 @@
 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`
+**Signature:** `(target: number | Uint8Array<ArrayBufferLike> | number[], model: any, commitId: number, SubStreamType: typeof StreamTypeBase<any>, delta: number) => void`
 
 **Parameters:**
 

package/skill/sendModel.md

@@ -3,7 +3,7 @@
 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`
+**Signature:** `(target: number | Uint8Array<ArrayBufferLike> | number[], model: any, commitId: number, StreamType: typeof StreamTypeBase<any>, changed?: Change) => void`
 
 **Parameters:**