lowlander 0.4.0 → 0.6.0

package/client/client.ts

@@ -200,9 +200,12 @@ export class Connection<T> {
     private reconnectAttempts = 0;
     /** @internal */
     public _proxyCounter = 0;
-    private onlineProxy = A.proxy(false);
+    private $state = A.proxy({online: false, error: undefined as undefined|string});
     private streamCache = new Map<string, StreamCacheEntry>();
 
+    /** @internal - allows storing Connection instances in Aberdeen proxies without re-proxying */
+    get [A.OPAQUE]() { return true as const; }
+
     /**
      * Type-safe proxy to the server-side API. Methods return `PromiseProxy` objects
      * that work reactively in Aberdeen scopes. `ServerProxy` returns include a
@@ -221,22 +224,36 @@ export class Connection<T> {
     /**
      * Returns the current connection status. Reactive in Aberdeen scopes.
      */
-    isOnline(): boolean { return this.onlineProxy.value; }
+    isOnline(): boolean { return this.$state.online; }
+
+    /**
+     * Returns the last WebSocket error message, or `undefined` if there is none.
+     * Clears automatically when the connection comes online. Reactive in Aberdeen scopes.
+     */
+    getError(): string | undefined { return this.$state.error; }
 
     private connect() {
-        const ws: WebSocket = this.ws = typeof this.url === 'string'
-            ? new WebSocket(this.url)
-            : this.url();
+        let ws: WebSocket;
+        try {
+            ws = this.ws = typeof this.url === 'string'
+                ? new WebSocket(this.url)
+                : this.url();
+        } catch (error: any) {
+            console.error('WebSocket connection error:', error);
+            this.$state.error = error?.message || 'WebSocket connection error';
+            return;
+        }
         ws.binaryType = "arraybuffer";
         if (logLevel >= 1) console.log(`[lowlander] Connecting to WebSocket at ${typeof this.url === 'string' ? this.url : '[custom WebSocket]'}`);
  
         ws.onopen = () => {
             if (ws !== this.ws) return; // No longer the current connection
             if (logLevel >= 1) console.log('[lowlander] WebSocket connected');
-            this.onlineProxy.value = true;
+            this.$state.online = true;
+            this.$state.error = undefined;
             this.reconnectAttempts = 0;
             for(const request of this.activeRequests.values()) {
-                request.resultProxy.busy = true;
+                request.$result.busy = true;
                 this.ws!.send(request.requestBuffer as Uint8Array<ArrayBuffer>);
             }
         };
@@ -250,6 +267,7 @@ export class Connection<T> {
         ws.onerror = (error: any) => {
             if (ws !== this.ws) return; // No longer the current connection
             console.error('WebSocket error:', error);
+            this.$state.error = error?.message || 'WebSocket connection error';
             this.reconnect();
         };
         
@@ -261,7 +279,7 @@ export class Connection<T> {
 
             const request = this.activeRequests.get(requestId);
             if (!request) return; // Raced
-            const result = A.unproxy(request.resultProxy);
+            const result = A.unproxy(request.$result);
 
             const type = pack.read();
             if (typeof type === 'number') {
@@ -318,12 +336,12 @@ export class Connection<T> {
                 } else {
                     // Create new object
                     if (prevCommitIds && commitId < (prevCommitIds.get(DEFAULT_COMMIT) ?? -1)) return; // Stale create
-                    const entry = A.proxy(delta);
+                    const $entry = A.proxy(delta);
                     // OPAQUE=false: excluded from A.copy recursion (so this proxy is never
                     // corrupted by being overwritten with data from a different linked model
                     // at the same array index), but still wrapped in a proxy on read.
-                    (A.unproxy(entry) as any)[A.OPAQUE] = false;
-                    request.database.set(dbKeyHash, entry);
+                    (A.unproxy($entry) as any)[A.OPAQUE] = false;
+                    request.database.set(dbKeyHash, $entry);
                     request.commitIds.set(dbKeyHash, new Map([[DEFAULT_COMMIT, commitId]]));
                 }
                 return;
@@ -332,11 +350,11 @@ export class Connection<T> {
             // Each request should get one of these packet types as a response
             if (type === SERVER_MESSAGES.error) {
                 const errorMessage = pack.readString();
-                request.resultProxy.error = new Error(errorMessage);
+                request.$result.error = new Error(errorMessage);
                 if (logLevel >= 2) console.log(`[lowlander] incoming error requestId=${requestId} message=${errorMessage}`);
 
             } else if (type === SERVER_MESSAGES.response || type === SERVER_MESSAGES.response_proxy) {
-                request.resultProxy.value = pack.read();
+                request.$result.value = pack.read();
                 request.virtualSocketIds = pack.read() as number[] | undefined;
                 request.hasServerProxy = type === SERVER_MESSAGES.response_proxy;
                 if (logLevel >= 2) console.log(`[lowlander] incoming response requestId=${requestId} value=${result.value} virtualSocketIds=${request.virtualSocketIds} hasServerProxy=${request.hasServerProxy}`);
@@ -349,9 +367,9 @@ export class Connection<T> {
                 request.hasServerProxy = type === SERVER_MESSAGES.response_proxy_model;
                 if (logLevel >= 2) console.log(`[lowlander] incoming ${request.hasServerProxy ? 'response_proxy_model' : 'response_model'} requestId=${requestId} dbKey=${dbKey} cacheMs=${cacheMs} obj=${obj}`);
                 if (obj) {
-                    request.resultProxy.value = A.proxy(obj);
+                    request.$result.value = A.proxy(obj);
                 } else {
-                    request.resultProxy.error = new Error('Unknown database key ' + dbKey);
+                    request.$result.error = new Error('Unknown database key ' + dbKey);
                 }
                 if (cacheMs !== undefined && request.cacheKey && !this.streamCache.has(request.cacheKey)) {
                     this.streamCache.set(request.cacheKey, {
@@ -370,10 +388,10 @@ export class Connection<T> {
             }
 
             if (!request.hasServerProxy) {
-                delete (request.resultProxy as any).serverProxy;
+                delete (request.$result as any).serverProxy;
             }
 
-            request.resultProxy.busy = false;
+            request.$result.busy = false;
 
             if (request.resolve) {
                 // This does not happen on reconnect
@@ -392,7 +410,7 @@ export class Connection<T> {
     private reconnect() {
         this.ws = undefined;
 
-        this.onlineProxy.value = false;
+        this.$state.online = false;
 
         if (typeof this.url !== 'string') return; // No reconnect in test mode
 
@@ -438,12 +456,12 @@ export class Connection<T> {
                         if (cached.refCount <= 0) this.startLinger(cached);
                     });
 
-                    return cached.request.resultProxy;
+                    return cached.request.$result;
                 }
             }
 
             const result = {busy: true} as PromiseProxy<any> & {promise: Promise<any>} & {serverProxy: any};
-            const resultProxy = A.proxy(result);
+            const $result = A.proxy(result);
 
             const requestId = ++this.requestCounter;
 
@@ -463,7 +481,7 @@ export class Connection<T> {
                 }
             });
 
-            const request: ActiveRequest = { resultProxy, requestBuffer: pack.toUint8Array(true), requestId, connection: this, callbacks, cacheKey };
+            const request: ActiveRequest = { $result, requestBuffer: pack.toUint8Array(true), requestId, connection: this, callbacks, cacheKey };
             result.serverProxy = new Proxy(request, proxyHandlers);
             result.promise = new Promise((resolve, reject) => {
                 request.resolve = resolve;
@@ -489,7 +507,7 @@ export class Connection<T> {
                 this.cancelRequest(request);
             });
 
-            return resultProxy;
+            return $result;
         }
     }
 
@@ -520,7 +538,12 @@ export class Connection<T> {
 }
 
 const proxyHandlers: ProxyHandler<any> = {
-    get(target: ProxyTargetType, prop: string) {
+    get(target: ProxyTargetType, prop: string | symbol) {
+        if (typeof prop === 'symbol') {
+            // Expose OPAQUE=true so Aberdeen stores us as-is without re-proxying.
+            // Also, don't dive into object args
+            return prop === A.OPAQUE ? true : prop === A.CUSTOM_DUMP ? `<ServerProxy for #${target.requestId}>` : undefined;
+        }
         if (target.serverProxyCache?.has(prop)) {
             return target.serverProxyCache.get(prop);
         }
@@ -548,7 +571,7 @@ interface ProxyTargetType {
 }
 
 interface ActiveRequest extends ProxyTargetType {
-    resultProxy: PromiseProxy<any>;
+    $result: PromiseProxy<any>;
     callbacks?: ((...args: any[]) => void)[];
     virtualSocketIds?: number[];
     database?: Map<number, Record<any,any>>; // For model streams

package/dashboard/build-bundle.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Bundles dashboard/client/main.ts into build/dashboard/dashboard.html as a
+// single self-contained file.
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import * as esbuild from 'esbuild';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, '..');
+const outDir = resolve(root, 'build/dashboard');
+mkdirSync(outDir, { recursive: true });
+
+const debug = process.argv.includes('--debug');
+const result = await esbuild.build({
+    entryPoints: [resolve(here, 'client/main.ts')],
+    bundle: true,
+    platform: 'browser',
+    format: 'esm',
+    minify: !debug,
+    sourcemap: debug ? 'inline' : false,
+    write: false,
+    tsconfig: resolve(root, 'tsconfig.client.json'),
+});
+if (debug) {
+    const dbgJs = result.outputFiles[0].text;
+    console.log('Symbol("target") occurrences (>1 means duplicate Aberdeen):',
+        (dbgJs.match(/Symbol\("target"\)/g) || []).length);
+}
+if (result.errors.length) {
+    for (const e of result.errors) console.error(e.text);
+    process.exit(1);
+}
+const js = result.outputFiles[0].text;
+
+const template = readFileSync(resolve(here, 'client/index.html'), 'utf8');
+const scriptTag = `<script type="module">${js.replace(/<\/script>/gi, '<\\/script>')}</script>`;
+// Use a function replacer so $& / $' / $` in the bundle are never treated as
+// special replacement patterns by String.replace.
+const html = template.replace('<!--LOWLANDER_DASHBOARD_SCRIPT-->', () => scriptTag);
+
+const outFile = resolve(outDir, 'dashboard.html');
+writeFileSync(outFile, html);
+console.log(`Dashboard bundled: ${outFile} (${(html.length / 1024).toFixed(1)} KB)`);