lowlander 0.3.0 → 0.5.0

package/skill/SKILL.md

@@ -25,17 +25,25 @@ This library is built on top of a number of libraries by the same author:
 
 Lowlander glues these together and adds real-time partial data synchronization and type-safe RPCs to provide a framework for rapidly building performant full-stack (database included!) web applications.
 
+## Example project
+
+An example project is included in `examples/helloworld`. To run it:
+
+```bash
+npm run example
+```
+
+Opens at http://localhost:8080 with the Aberdeen dashboard at http://localhost:8080/_dashboard (password printed to console on start).
+
 ## Tutorial
 
 ### Project Setup
 
 ```bash
-bun init
-bun add lowlander aberdeen edinburgh
+npm init
+npm add lowlander aberdeen edinburgh
 ```
 
-(npm should also work for all of this.)
-
 Create the project structure:
 
 ```
@@ -179,6 +187,20 @@ 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
@@ -295,6 +317,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:
@@ -306,10 +347,50 @@ Set the `LOWLANDER_LOG_LEVEL` environment variable to a number from 0 to 3:
 
 Set `EDINBURGH_LOG_LEVEL` similarly for Edinburgh internals.
 
+### Dashboard
+
+Lowlander ships with an optional admin/developer dashboard for inspecting
+Edinburgh models, browsing index rows, listing RPC methods, viewing source
+code, and peeking at warpsocket debug state (channels, sockets, workers,
+KV). It's a single self-contained HTML bundle.
+
+To enable it:
+
+1. Re-export `_dashboard` from your top-level API module:
+
+   ```ts
+   // server/api.ts
+   export { _dashboard } from "lowlander/dashboard";
+   ```
+
+2. Serve the bundled HTML by calling `serveDashboard(res)` from a
+   `warpsocket` `handleHttpRequest` export:
+
+   ```ts
+   import type { HttpRequest, HttpResponse } from "warpsocket";
+   import { serveDashboard } from "lowlander/dashboard";
+
+   export function handleHttpRequest(req: HttpRequest, res: HttpResponse) {
+       if (req.url === '/_dashboard' || req.url.startsWith('/_dashboard?')) {
+           return serveDashboard(res);
+       }
+       // … serve your own static files …
+   }
+   ```
+
+3. On first server start (per warpsocket KV namespace), a random password
+   is generated and printed to the console. Override with the
+   `LOWLANDER_DASHBOARD_PASSWORD` env var.
+
+The dashboard prompts for the websocket URL (defaults to the current host)
+and password on first load, then stores them in localStorage.
+
 ## Server API Reference
 
 The following is auto-generated from `server/server.ts`:
 
+### [getStreamTypesForModel](getStreamTypesForModel.md) · function
+
 ### [createStreamType](createStreamType.md) · function
 
 Creates a stream type for reactive model streaming to clients with automatic updates.

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: (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`
+**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:**
 

package/skill/getStreamTypesForModel.md

@@ -0,0 +1,7 @@
+### getStreamTypesForModel · function
+
+**Signature:** `(Model: AnyModelClass) => readonly (typeof StreamTypeBase<unknown>)[]`
+
+**Parameters:**
+
+- `Model: E.AnyModelClass`