lowlander 0.5.0 → 0.6.0

package/dashboard/server.ts

@@ -18,13 +18,111 @@ function passwordOk(provided: string): boolean {
     return timingSafeEqual(Buffer.from(provided), Buffer.from(expected));
 }
 
-function describeType(type: E.TypeWrapper<unknown>): { kind: string; display: string; linkedModel?: string } {
+/** Recursive type descriptor sent to the dashboard client for building CRUD editors. */
+export interface TypeInfo {
+    kind: string;
+    display: string;
+    /** For 'link' kind: the linked model's tableName. */
+    linkedModel?: string;
+    /** For 'array', 'set', and opt('or' with undef) kinds: the element/inner type. */
+    inner?: TypeInfo;
+    /** For 'record' kind: the value type. */
+    innerValue?: TypeInfo;
+    /** For 'or' kind: all union choices (includes the undef literal for opt). */
+    choices?: TypeInfo[];
+    /** True when this is opt(T) — an or(undef, T) with exactly one non-undefined branch. */
+    isOptional?: boolean;
+    /** For 'literal' kind: the JSON-serialized literal value. */
+    literalValue?: string;
+}
+
+function describeType(type: E.TypeWrapper<unknown>): TypeInfo {
+    const kind = (type as any).kind as string;
     const linked = type.getLinkedModel();
-    return {
-        kind: (type as any).kind,
+
+    const info: TypeInfo = {
+        kind,
         display: type.toString(),
         linkedModel: linked?.tableName,
     };
+
+    if (kind === 'array' || kind === 'set') {
+        info.inner = describeType((type as any).inner);
+    } else if (kind === 'record') {
+        info.innerValue = describeType((type as any).inner);
+    } else if (kind === 'or') {
+        const choices = (type as any).choices as E.TypeWrapper<unknown>[];
+        info.choices = choices.map(describeType);
+        const isUndefLiteral = (t: TypeInfo) => t.kind === 'literal' && t.literalValue === 'undefined';
+        const nonUndef = info.choices.filter(c => !isUndefLiteral(c));
+        const hasUndef = info.choices.some(c => isUndefLiteral(c));
+        if (hasUndef && nonUndef.length === 1) {
+            info.isOptional = true;
+            info.inner = nonUndef[0];
+        }
+    } else if (kind === 'literal') {
+        const val = (type as any).value;
+        info.literalValue = val === undefined ? 'undefined' : JSON.stringify(val);
+    }
+
+    return info;
+}
+
+function parseValueFromJson(type: E.TypeWrapper<unknown>, json: any): any {
+    if (json === null || json === undefined) return undefined;
+    const kind = (type as any).kind as string;
+    switch (kind) {
+        case 'string':
+        case 'id':
+            return typeof json === 'string' ? json : String(json);
+        case 'number':
+            return typeof json === 'number' ? json : Number(json);
+        case 'boolean':
+            return json === true || json === 'true' || json === 1;
+        case 'dateTime':
+            return new Date(json);
+        case 'link': {
+            const Model = type.getLinkedModel()!;
+            const pk = json?.__ref ? json.pk : json;
+            const pkArgs = Array.isArray(pk) ? pk : [pk];
+            const instance = (Model as any).get(...pkArgs);
+            if (!instance) throw new Error(`Linked ${Model.tableName} record not found: ${JSON.stringify(pk)}`);
+            return instance;
+        }
+        case 'array': {
+            const inner = (type as any).inner as E.TypeWrapper<unknown>;
+            if (!Array.isArray(json)) return [];
+            return json.map((v: any) => parseValueFromJson(inner, v));
+        }
+        case 'set': {
+            const inner = (type as any).inner as E.TypeWrapper<unknown>;
+            if (!Array.isArray(json)) return new Set();
+            return new Set(json.map((v: any) => parseValueFromJson(inner, v)));
+        }
+        case 'record': {
+            const inner = (type as any).inner as E.TypeWrapper<unknown>;
+            if (!json || typeof json !== 'object' || Array.isArray(json)) return {};
+            const result: Record<string, any> = {};
+            for (const [k, v] of Object.entries(json)) result[k] = parseValueFromJson(inner, v);
+            return result;
+        }
+        case 'or': {
+            const choices = (type as any).choices as E.TypeWrapper<unknown>[];
+            const isUndefLiteral = (t: E.TypeWrapper<unknown>) =>
+                (t as any).kind === 'literal' && (t as any).value === undefined;
+            if (json === null || json === undefined) {
+                if (choices.some(isUndefLiteral)) return undefined;
+                return null;
+            }
+            const nonUndef = choices.filter(c => !isUndefLiteral(c));
+            if (nonUndef.length === 1) return parseValueFromJson(nonUndef[0]!, json);
+            return json;
+        }
+        case 'literal':
+            return (type as any).value;
+        default:
+            return json;
+    }
 }
 
 function describeIndex(index: any) {
@@ -38,18 +136,21 @@ function describeIndex(index: any) {
 }
 
 function describeModel(Model: E.AnyModelClass) {
-    const fields: { name: string; type: ReturnType<typeof describeType>; description?: string; hasDefault: boolean }[] = [];
+    const pkIdx = describeIndex(Model);
+    const pkFields = new Set(pkIdx.fields);
+    const fields: { name: string; type: TypeInfo; description?: string; hasDefault: boolean; isPk: boolean }[] = [];
     for (const [name, cfg] of Object.entries(Model.fields) as [string, E.FieldConfig<unknown>][]) {
         fields.push({
             name,
             type: describeType(cfg.type),
             description: cfg.description,
             hasDefault: cfg.default !== undefined,
+            isPk: pkFields.has(name),
         });
     }
     const indexes: { name: string; info: ReturnType<typeof describeIndex> }[] = [{
         name: '(primary)',
-        info: describeIndex(Model),
+        info: pkIdx,
     }];
     for (const [name, idx] of Object.entries((Model as any)._secondaries || {})) {
         indexes.push({ name, info: describeIndex(idx) });
@@ -216,6 +317,49 @@ class DashboardAPI {
         return new ST(instance);
     }
 
+    async createRecord(modelName: string, values: Record<string, any>): Promise<any> {
+        const Model = modelByName(modelName);
+        const parsed: Record<string, any> = {};
+        for (const [fieldName, jsonValue] of Object.entries(values)) {
+            const fieldConfig = Model.fields[fieldName] as E.FieldConfig<unknown> | undefined;
+            if (!fieldConfig) continue;
+            if ((fieldConfig.type as any).kind === 'id') continue; // auto-generated
+            const v = parseValueFromJson(fieldConfig.type, jsonValue);
+            if (v !== undefined) parsed[fieldName] = v;
+        }
+        return await E.transact(() => {
+            const instance = new (Model as any)(parsed);
+            const cls: any = instance.constructor;
+            const pkBytes = instance.getPrimaryKey?.();
+            const pkArr = pkBytes && cls._pkToArray ? cls._pkToArray(pkBytes) : null;
+            const pk = pkArr ? (pkArr.length === 1 ? pkArr[0] : pkArr) : null;
+            return serializeValue(pk);
+        });
+    }
+
+    async updateRecord(modelName: string, pk: any, values: Record<string, any>): Promise<void> {
+        const Model = modelByName(modelName);
+        const pkArgs = Array.isArray(pk) ? pk : [pk];
+        const instance = (Model as any).get(...pkArgs);
+        if (!instance) throw new Error(`Record not found: ${JSON.stringify(pk)}`);
+        await E.transact(() => {
+            for (const [fieldName, jsonValue] of Object.entries(values)) {
+                const fieldConfig = Model.fields[fieldName] as E.FieldConfig<unknown> | undefined;
+                if (!fieldConfig) continue;
+                if ((fieldConfig.type as any).kind === 'id') continue; // immutable
+                (instance as any)[fieldName] = parseValueFromJson(fieldConfig.type, jsonValue);
+            }
+        });
+    }
+
+    async deleteRecord(modelName: string, pk: any): Promise<void> {
+        const Model = modelByName(modelName);
+        const pkArgs = Array.isArray(pk) ? pk : [pk];
+        const instance = (Model as any).get(...pkArgs);
+        if (!instance) throw new Error(`Record not found: ${JSON.stringify(pk)}`);
+        await E.transact(() => { instance.delete(); });
+    }
+
     getDebugState(mode: 'channels' | 'sockets' | 'workers' | 'kv') {
         return warpsocket.getDebugState(mode as any);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lowlander",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "TypeScript framework for data persistence, type-safe RPCs and real-time (partial) client synchronization.",
   "type": "module",
   "main": "./build/server/server.js",
@@ -40,8 +40,10 @@
     "build:docs": "rm -rf skill ; mkdir skill ; cat skill-header.md README.md > skill/SKILL.md && readme-tsdoc --split --file skill/SKILL.md && readme-tsdoc --repo-url https://github.com/vanviegen/lowlander",
     "typecheck": "npx tsc -b",
     "clean": "rm -rf build dist skill",
-    "prepack": "npm install && npm run build",
+    "prepack": "npm run build",
     "test": "vitest run",
+    "test:e2e": "shotest test",
+    "test:e2e:review": "shotest review",
     "example": "npm run build && (cd examples/helloworld && npm install) && node build/examples/helloworld/server/main.js",
     "postinstall": "[ -f .local-post-install.sh ] && sh .local-post-install.sh || true"
   },
@@ -49,15 +51,17 @@
     "warpsocket": "^0.9.1"
   },
   "peerDependencies": {
-    "aberdeen": "^1.15.0",
+    "aberdeen": "^1.17.1",
     "edinburgh": "^0.6.4"
   },
   "devDependencies": {
     "@types/node": "^20.19.41",
-    "aberdeen": "^1.15.0",
+    "aberdeen": "^1.17.1",
     "esbuild": "^0.28.0",
-    "readme-tsdoc": "^1.1.6",
+    "readme-tsdoc": "^1.1.8",
+    "shotest": "^1.6.1",
     "sirv": "^3.0.2",
+    "staffa": "0.3.1",
     "tsx": "^4.0.0",
     "vitest": "^4.1.7"
   },

package/server/server.ts

@@ -37,8 +37,8 @@ export function getStreamTypesForModel(Model: E.AnyModelClass): readonly (typeof
  * @internal
  */
 export abstract class StreamTypeBase<T> {
-    /** @internal */
-    static fields: { [key: string]: true|number };
+    /** @internal `true`=plain field, number=sub-stream id, `false`=virtual getter */
+    static fields: { [key: string]: boolean|number };
     /** @internal */
     static id: number;
     /** @internal */
@@ -136,7 +136,11 @@ function getIdForData(namespace: string, ...data: any): number {
 
     const countKey = new DataPack().write(namespace).toUint8Array();
     while(true) {
-        // Insert a new stream type
+        // Another worker may have won the race since we last checked
+        const existingPack = warpsocket.getKey(dataKey);
+        if (existingPack) {
+            return new DataPack(existingPack).readNumber();
+        }
         const countPack = warpsocket.getKey(countKey);
         const newCount = countPack ? new DataPack(countPack).readNumber() + 1 : 1;
         const newCountPack = new DataPack().write(newCount).toUint8Array();
@@ -190,25 +194,33 @@ export function createStreamType<T, S extends FieldSelection<T>>(
   Model: E.AnyModelClass & (new (...args: any[]) => T),
   selection: S & ValidateSelection<T, S>,
   options?: { cache?: number }
-): { new(instance: T): StreamTypeBase<Project<T, S>>; id: number; fields: Record<string, true|number>; cache?: number } {
+): { new(instance: T): StreamTypeBase<Project<T, S>>; id: number; fields: Record<string, boolean|number>; cache?: number } {
     let streamTypes = streamTypesPerModel.get(Model);
     if (!streamTypes) streamTypesPerModel.set(Model, streamTypes = []);
 
     const streamTypeId = getIdForData("streamType", Model.tableName, selection);
 
-    const fields: Record<string, true|number> = {};
+    const fields: Record<string, boolean|number> = {};
     for(const prop of Array.from(Object.keys(selection)).sort() as (string & keyof S)[]) {
+        const sel = (selection as any)[prop];
+
         if (!Model.fields.hasOwnProperty(prop)) {
+            // Allow selecting a getter on the model prototype as a virtual field
+            const desc = Object.getOwnPropertyDescriptor((Model as any).prototype, prop);
+            if (desc?.get && sel === true) {
+                fields[prop] = false;
+                continue;
+            }
             throw new Error(`Property ${prop} does not exist in model ${Model.name}`);
         }
         const LinkedModel = Model.fields[prop].type.getLinkedModel() as E.AnyModelClass | undefined;
 
-        if (selection[prop] === true) {
+        if (sel === true) {
             if (LinkedModel) throw new Error(`Property ${prop} is a link; must specify sub-selection`);
             fields[prop] = true; // Include field without tracking links
         } else {
             if (!LinkedModel) throw new Error(`Property ${prop} is not a link; cannot specify sub-selection`);
-            const SubStreamType = createStreamType(LinkedModel as any, selection[prop] as any)
+            const SubStreamType = createStreamType(LinkedModel as any, sel as any)
             fields[prop] = SubStreamType.id;
         }
     }
@@ -261,6 +273,14 @@ function updateLinkDeltas(value: any, linkDeltas: Map<E.Model<unknown>, Map<numb
     }
 }
 
+/** Loose deep equality for getter result comparison (primitives via Object.is, objects via JSON). */
+function valuesEqual(a: any, b: any): boolean {
+    if (Object.is(a, b)) return true;
+    if (a == null || b == null) return false;
+    if (typeof a !== 'object' || typeof b !== 'object') return false;
+    try { return JSON.stringify(a) === JSON.stringify(b); } catch { return false; }
+}
+
 E.setOnSaveCallback((commitId: number, items: Map<E.Model<any>, E.Change>) => {
     if (logLevel >= 3) console.log('[lowlander] onSave', commitId);
     for(const [model, changed] of items.entries()) {
@@ -303,10 +323,24 @@ export function sendModel(target: Uint8Array | number | number[], model: E.Model
     else { // changed is an object or 'created'
         const linkDeltas = new Map<E.Model<unknown>, Map<number,number>>();
 
+        let oldClone: any;
+
         pack.writeCollection('object', (addRecord) => {
             for(const fieldName in StreamType.fields) {
+                const streamIndex = StreamType.fields[fieldName];
+
+                if (streamIndex === false) {
+                    const newVal = (model as any)[fieldName];
+                    if (typeof changed === 'object') {
+                        oldClone ??= Object.assign(Object.create(model), changed);
+                        if (valuesEqual(oldClone[fieldName], newVal)) continue;
+                    }
+                    addRecord(fieldName, newVal);
+                    mustSend = true;
+                    continue;
+                }
+
                 if (typeof changed === 'object' && !changed.hasOwnProperty(fieldName)) continue;
-                let streamIndex = StreamType.fields[fieldName];
 
                 let fieldValue = (model as any)[fieldName];
                 mustSend = true;
@@ -437,6 +471,7 @@ export class Socket<T> {
         return `{Socket id=${this.virtualSocketId}}`;
     }
 
+    /** @internal */
     [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.toString();
     }

package/skill/SKILL.md

@@ -35,6 +35,10 @@ npm run example
 
 Opens at http://localhost:8080 with the Aberdeen dashboard at http://localhost:8080/_dashboard (password printed to console on start).
 
+This is what the example dashboard looks like:
+
+![dashboard screenshot](dashboard_screenshot.png)
+
 ## Tutorial
 
 ### Project Setup
@@ -158,6 +162,24 @@ const PersonStream = createStreamType(Person, fields, { cache: 30 }); // cache f
 
 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.
 
+#### Virtual (computed) fields
+
+Plain getter properties on the model can be selected like any other field. Lowlander detects them and re-evaluates on each commit; an update is pushed only when the getter's return value actually changes:
+
+```ts
+const Person = E.defineModel('Person', class {
+    name = E.field(E.string);
+    age  = E.field(E.number);
+    get greeting() { return `Hi, I'm ${this.name} and I'm ${this.age}!`; }
+}, { pk: 'name' });
+
+const PersonStream = createStreamType(Person, {
+    greeting: true,
+});
+```
+
+On every model update, `greeting` will be invoked for both the old and new data, to check for changes. So avoid doing expensive operations in these getters.
+
 ### ServerProxy for Stateful APIs
 
 Wrap a class instance to expose per-connection stateful methods:
@@ -417,7 +439,7 @@ Starts the Lowlander WebSocket server.
 
 ### StreamTypeBase · abstract class
 
-[object Object],[object Object],[object Object]
+Base class for stream types created by .
 
 **Type Parameters:**
 
@@ -425,7 +447,7 @@ Starts the Lowlander WebSocket server.
 
 #### StreamTypeBase.fields · static property
 
-**Type:** `{ [key: string]: number | true; }`
+**Type:** `{ [key: string]: number | boolean; }`
 
 #### StreamTypeBase.id · static property
 
@@ -494,29 +516,9 @@ Transforms server-side API objects to client-side proxy objects with type-safe R
 WebSocket connection to a Lowlander server with type-safe RPC, automatic reconnection,
 and reactive updates.
 
-#### connection.ws · property
-
-**Type:** `WebSocket`
-
-#### connection.activeRequests · property
-
-**Type:** `Map<number, ActiveRequest>`
-
-#### connection.requestCounter · property
-
-**Type:** `number`
+#### connection.[A.OPAQUE] · getter
 
-#### connection.reconnectAttempts · property
-
-**Type:** `number`
-
-#### connection.onlineProxy · property
-
-**Type:** `ValueRef<boolean>`
-
-#### connection.streamCache · property
-
-**Type:** `Map<string, StreamCacheEntry>`
+**Type:** `true`
 
 #### connection.api · property
 
@@ -532,29 +534,10 @@ Returns the current connection status. Reactive in Aberdeen scopes.
 
 **Signature:** `() => boolean`
 
-#### connection.connect · method
-
-**Signature:** `() => void`
-
-#### connection.reconnect · method
-
-**Signature:** `() => void`
-
-#### [connection.pruneCommitIds](Connection_pruneCommitIds.md) · method
+#### connection.getError · method
 
-#### connection.cancelRequest · method
+Returns the last WebSocket error message, or `undefined` if there is none.
+Clears automatically when the connection comes online. Reactive in Aberdeen scopes.
 
-**Signature:** `(request: ActiveRequest) => void`
-
-**Parameters:**
-
-- `request: ActiveRequest`
-
-#### connection.startLinger · method
-
-**Signature:** `(cached: StreamCacheEntry) => void`
-
-**Parameters:**
-
-- `cached: StreamCacheEntry`
+**Signature:** `() => string`
 

package/skill/Connection_pruneCommitIds.md

@@ -1,8 +0,0 @@
-#### connection.pruneCommitIds · method
-
-**Signature:** `(request: ActiveRequest, maxCommitId: number) => void`
-
-**Parameters:**
-
-- `request: ActiveRequest`
-- `maxCommitId: number`