lowlander 0.2.4 → 0.4.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,33 @@ 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) {
                     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);
+
+                    if (response.value instanceof StreamTypeBase) {
+                        const StreamType = response.value.constructor as typeof StreamTypeBase<any>;
+                        const instance = response.value._instance;
+
+                        const virtualSocketId = warpsocket.createVirtualSocket(socketId, DataPack.createUint8Array(requestId, SERVER_MESSAGES.model_data));
+                        virtualSocketIds.push(virtualSocketId);
+                        pushModel(virtualSocketId, instance, 0, StreamType, 1);
+
+                        const cacheMs = StreamType.cache !== undefined ? StreamType.cache * 1000 : undefined;
+                        pendingPacket = DataPack.createUint8Array(requestId, SERVER_MESSAGES.response_proxy_model, virtualSocketIds, instance.getPrimaryKeyHash() + StreamType.id, cacheMs);
+                    } else {
+                        pendingPacket = DataPack.createUint8Array(requestId, SERVER_MESSAGES.response_proxy, response.value, virtualSocketIds);
+                    }
 
                 } else if (response instanceof StreamTypeBase) {
                     const StreamType = response.constructor as typeof StreamTypeBase<any>;
@@ -116,14 +140,14 @@ export async function handleBinaryMessage(message: Uint8Array, socketId: number)
 
                     // Then respond, indicating which row should be top level
                     const cacheMs = StreamType.cache !== undefined ? StreamType.cache * 1000 : undefined;
-                    pendingSend = () => send(socketId, requestId, SERVER_MESSAGES.response_model, virtualSocketIds, instance.getPrimaryKeyHash() + StreamType.id, cacheMs);
+                    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');
@@ -133,7 +157,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,7 +125,7 @@ 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);
 }
 ```
@@ -157,13 +155,14 @@ After a stream with caching goes out of scope, the server keeps it alive for tha
 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() {
@@ -172,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');
 }
@@ -180,6 +179,28 @@ export async function authenticate(token: string) {
 
 The client receives `'secret-value'` as `.value` and can call `UserAPI` methods via `.serverProxy`.
 
+You can also pass a stream type instance as the value — the client's `.value` will then be reactive and update live whenever the model changes:
+
+```ts
+const PersonStream = createStreamType(Person, { name: true, age: true });
+
+export async function authenticate(token: string) {
+    const user = Person.getBy('name', token);
+    if (!user) throw new Error('User not found');
+    return new ServerProxy(new UserAPI(token), new PersonStream(user));
+}
+```
+
+The client gets both `.serverProxy` (for calling `UserAPI` methods) and a live-updating `.value`.
+
+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:
@@ -288,6 +309,25 @@ Reconnection is automatic with exponential backoff.
 
 Aberdeen's `clean()` handles RPC lifecycle. When a reactive scope is destroyed, active requests and subscriptions are cancelled automatically.
 
+
+#### Named Client-Side Types
+
+Use `ClientProxyObject<T>` to get the fully-typed client API shape, which is useful for deriving types from stream methods without duplicating field selections:
+
+```ts
+import type { ClientProxyObject } from 'lowlander/client';
+import type * as API from './server/api.js';
+
+type APIClient = ClientProxyObject<typeof API>;
+const api: APIClient = new Connection<typeof API>('ws://localhost:8080/').api;
+
+type SomethingType = ReturnType<APIClient['streamSomething']>;
+const something: SomethingType = api.streamSomething();
+```
+
+`ClientProxyObject` maps server return types to their client-side equivalents. Stream methods return `PromiseProxy<ProjectedData>`, plain values return `PromiseProxy<T>`, and `ServerProxy<API, R>` methods return a proxy with a `.serverProxy` of type `ClientProxyObject<SubAPI>`.
+
+
 ### Logging
 
 Set the `LOWLANDER_LOG_LEVEL` environment variable to a number from 0 to 3:

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>, options?: { cache?: number; }) => typeof StreamType`
+**Signature:** `<T, S extends FieldSelection<T>>(Model: object & ModelClassRuntime<any, readonly any[], any, any> & (new (initial?: Partial<any>, txn?: Transaction) => any) & (new (...args: any[]) => T), selection: S & ValidateSelection<...>, options?: { ...; }) => { ...; }`
 
 **Type Parameters:**
 
@@ -14,7 +14,7 @@ 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
 
@@ -23,13 +23,12 @@ Supports nested linked models and type-safe field selection.
 **Examples:**
 
 ```ts
-⁣@E.registerModel
-class Person extends Model {
-  name = field(string);
-  age = field(number);
-  password = field(string);
-  friends = field(array(link(Person)));
-}
+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, {
@@ -39,7 +38,7 @@ const PersonStream = createStreamType(Person, {
 }, { 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:**