holosphere 1.3.0-alpha4 → 1.3.0-alpha7

package/holosphere.d.ts

@@ -15,11 +15,39 @@ interface PutOptions {
   disableHologramRedirection?: boolean;
   actingAs?: string;
   password?: string | null;
+  /**
+   * Per-put deadline (ms) for Gun's ack callback. When the deadline fires,
+   * the returned promise resolves with `{ success: true, queued: true, ... }`
+   * so an offline/partitioned mesh can't hang the caller — Gun keeps the
+   * write locally and replays it on reconnect. Default 5000. Pass `0` to
+   * disable and wait for ack indefinitely.
+   */
+  timeout?: number;
+}
+
+interface PutGlobalOptions {
+  /**
+   * Per-put deadline (ms) for Gun's ack callback. The promise still
+   * resolves to `undefined` (its public contract); on timeout a warning
+   * is logged. Default 5000. Pass `0` to disable.
+   */
+  timeout?: number;
 }
 
 interface GetOptions {
   resolveHolograms?: boolean;
   validationOptions?: object;
+  /** Per-`.once()` deadline in ms; cold paths resolve `null` after this. Default 8000. Pass `0` to disable. */
+  timeout?: number;
+  /** Return `_deleted: true` soft-tombstoned records instead of treating them as not-found. Default false. */
+  includeDeleted?: boolean;
+}
+
+interface GetAllOptions {
+  /** Per-`.once()` deadline in ms; cold paths resolve `[]` after this. Default 8000. Pass `0` to disable. */
+  timeout?: number;
+  /** Include `_deleted: true` soft-tombstoned records in the response. Default false. */
+  includeDeleted?: boolean;
 }
 
 interface ResolveHologramOptions {
@@ -42,22 +70,69 @@ interface Hologram {
  *
  * On success: `isHologram === true` and source* fields point at the origin.
  * On failure: `isHologram === false` and `error` describes why resolution failed.
+ *
+ * **Exported.** Domain types in consumers should declare
+ * `_hologram?: ResolvedHologramMeta` instead of inlining the shape.
  */
-interface ResolvedHologramMeta {
+export interface ResolvedHologramMeta {
   isHologram: boolean;
   soul: string;
   sourceHolon?: string | null;
   sourceLens?: string | null;
   sourceKey?: string | null;
+  /** Display name of the source holon — stamped by `resolveHologram` when known. */
+  sourceHolonName?: string;
   resolvedAt: number;
   error?: string;
 }
 
-interface ResolvedHologramData {
+export interface ResolvedHologramData {
   _hologram: ResolvedHologramMeta;
   [key: string]: any;
 }
 
+/**
+ * Federation provenance envelope stamped on records that arrived via a
+ * federated partner. Set by `getFederated` and by `propagate` when writing
+ * to outbound partners.
+ *
+ * **Exported.** Domain types should declare `_federation?: FederationMeta`
+ * instead of inlining the shape.
+ */
+export interface FederationMeta {
+  /** The holon the record was propagated FROM. */
+  origin: string;
+  /** The lens it was published under at the origin. */
+  sourceLens: string;
+  /** Origin holon's display name (best-effort; absent if the source has no name). */
+  originName?: string;
+  /** Source-side id of the record, useful when local-side keys differ. */
+  originalId?: string;
+  /** Wall-clock ms when the propagation was emitted. */
+  propagatedAt?: number;
+}
+
+/**
+ * Soft-tombstone marker recognised by `get`/`getAll`. A record with
+ * `_deleted: true` is treated as not-found in the default response and
+ * surfaced only when `{ includeDeleted: true }` is passed.
+ *
+ * **Exported.** Domain types that want to allow tombstoned records on the
+ * wire should declare `_deleted?: boolean`.
+ */
+export type DeletedMarker = boolean;
+
+/**
+ * Convenience mixin: the three envelope fields the library stamps onto
+ * records. Domain types can extend or intersect with this to avoid
+ * redeclaring the shapes.
+ */
+export interface HolosphereEnvelope {
+  _hologram?: ResolvedHologramMeta;
+  _federation?: FederationMeta;
+  _deleted?: DeletedMarker;
+}
+
 /**
  * Per-partner directional lens config. Directions are from the holding
  * space's perspective: `inbound` lenses are received from the partner,
@@ -123,6 +198,16 @@ interface PutResult {
   pathKey: string;
   propagationResult?: PropagationResult | null;
   error?: string;
+  /**
+   * `true` when the ack deadline fired before Gun confirmed the write
+   * (offline/partitioned mesh). The write is still committed locally
+   * via radisk and Gun replays it whenever a peer reappears; subscriber
+   * notification, hologram cascade, and federation propagation run at
+   * that point. Absent or `false` when the put was acknowledged.
+   */
+  queued?: boolean;
+  /** Holograms whose `updated` timestamp was bumped by this put (empty when the put timed out). */
+  updatedHolograms?: Array<{ soul: string; holon: string; lens: string; key: string }>;
 }
 
 interface CanWriteResult {
@@ -168,7 +253,7 @@ declare class HoloSphere {
     put(holon: string, lens: string, data: object, password?: string | null, options?: PutOptions): Promise<PutResult>;
     get(holon: string, lens: string): Promise<any | null>;
     get(holon: string, lens: string, key: string, password?: string | null, options?: GetOptions): Promise<any | null>;
-    getAll(holon: string, lens: string, password?: string | null): Promise<Array<any>>;
+    getAll(holon: string, lens: string, password?: string | null, options?: GetAllOptions): Promise<Array<any>>;
     parse(rawData: any): Promise<object | null>;
     delete(holon: string, lens: string, key: string, password?: string | null): Promise<boolean>;
     deleteAll(holon: string, lens: string, password?: string | null): Promise<boolean>;
@@ -181,14 +266,14 @@ declare class HoloSphere {
     deleteNode(holon: string, lens: string, key: string): Promise<boolean>;
 
     // Global
-    putGlobal(tableName: string, data: object, password?: string | null): Promise<void>;
-    writeGlobal(tableName: string, data: object): Promise<void>;
+    putGlobal(tableName: string, data: object, password?: string | null, options?: PutGlobalOptions): Promise<void>;
+    writeGlobal(tableName: string, data: object, options?: PutGlobalOptions): Promise<void>;
     getGlobal(tableName: string, key: string, password?: string | null): Promise<any | null>;
     getAllGlobal(tableName: string, password?: string | null): Promise<Array<any>>;
     deleteGlobal(tableName: string, key: string, password?: string | null): Promise<boolean>;
     deleteAllGlobal(tableName: string, password?: string | null): Promise<boolean>;
-    subscribeGlobal(lens: string, key: string | null, callback: (data: any, key?: string) => void, options?: { realtimeOnly?: boolean }): Promise<{ unsubscribe: () => void }>;
-    subscribeGlobal(lens: string, callback: (data: any, key?: string) => void): Promise<{ unsubscribe: () => void }>;
+    subscribeGlobal(lens: string, key: string | null, callback: (data: any, key?: string) => void, options?: { realtimeOnly?: boolean }): { unsubscribe: () => void };
+    subscribeGlobal(lens: string, callback: (data: any, key?: string) => void): { unsubscribe: () => void };
 
     // Hologram
     createHologram(holon: string, lens: string, data: { id: string, [key: string]: any }): Hologram;
@@ -210,8 +295,10 @@ declare class HoloSphere {
     getScalespace(lat: number, lng: number): string[];
     getHolonScalespace(holon: string): string[];
 
-    // Subscription
-    subscribe(holon: string, lens: string, callback: (data: any, key?: string) => void): Promise<{ unsubscribe: () => void }>;
+    // Subscription. Returns synchronously — `await` on the return value
+    // still works (await on a non-Promise resolves to the value), so both
+    // call styles produce the same `{ unsubscribe }` shape.
+    subscribe(holon: string, lens: string, callback: (data: any, key?: string) => void): { unsubscribe: () => void };
 
     // Federation - v1 style
     federate(holonId1: string, holonId2: string, password1?: string | null, password2?: string | null, bidirectional?: boolean, lensConfig?: { inbound?: string[], outbound?: string[] }): Promise<boolean>;

package/holosphere.js

@@ -125,6 +125,10 @@ class HoloSphere {
         // Initialize schema cache
         this.schemaCache = new Map();
 
+        // Holon-name cache so resolveHologram + getFederated don't refetch
+        // `settings/<holon>` for every hologram from the same source.
+        this._holonNameCache = new Map();
+
         // Initialize allowed authors set (for canWrite)
         this._allowedAuthors = new Set();
     }
@@ -192,8 +196,8 @@ class HoloSphere {
         return ContentOps.get(this, holon, lens, key, password, options);
     }
 
-    async getAll(holon, lens, password = null) {
-        return ContentOps.getAll(this, holon, lens, password);
+    async getAll(holon, lens, password = null, options = {}) {
+        return ContentOps.getAll(this, holon, lens, password, options);
     }
 
     async parse(rawData) {
@@ -232,15 +236,15 @@ class HoloSphere {
 
     // ================================ GLOBAL FUNCTIONS ================================
 
-    async putGlobal(tableName, data, password = null) {
-        return GlobalOps.putGlobal(this, tableName, data, password);
+    async putGlobal(tableName, data, password = null, options = {}) {
+        return GlobalOps.putGlobal(this, tableName, data, password, options);
     }
 
     /**
      * v2-compatible alias for putGlobal (no password param)
      */
-    async writeGlobal(tableName, data) {
-        return GlobalOps.putGlobal(this, tableName, data, null);
+    async writeGlobal(tableName, data, options = {}) {
+        return GlobalOps.putGlobal(this, tableName, data, null, options);
     }
 
     async getGlobal(tableName, key, password = null) {
@@ -262,8 +266,10 @@ class HoloSphere {
     /**
      * Subscribe to real-time changes in a global table.
      * v2-compatible: subscribeGlobal(lens, key, callback, options)
+     *
+     * Returns synchronously — see {@link subscribe}.
      */
-    async subscribeGlobal(lens, keyOrCallback, callbackOrOptions, options = {}) {
+    subscribeGlobal(lens, keyOrCallback, callbackOrOptions, options = {}) {
         let key, callback;
         if (typeof keyOrCallback === 'function') {
             callback = keyOrCallback;
@@ -336,7 +342,14 @@ class HoloSphere {
         return Utils.getHolonScalespace(holon);
     }
 
-    async subscribe(holon, lens, callback) {
+    /**
+     * Subscribe to real-time changes for a holon/lens.
+     *
+     * Synchronous return: `{ unsubscribe: () => void }`. Callers do not
+     * need to `await` — both `const s = holosphere.subscribe(...)` and
+     * `const s = await holosphere.subscribe(...)` yield the same shape.
+     */
+    subscribe(holon, lens, callback) {
         return Utils.subscribe(this, holon, lens, callback);
     }
 
@@ -344,6 +357,38 @@ class HoloSphere {
         return Utils.notifySubscribers(this, data);
     }
 
+    /**
+     * Resolve a holon's display name from its `settings/<holon>` record.
+     * Cached per-instance so repeated lookups (e.g. one per hologram in a
+     * federated batch) only fetch once. Returns `null` when no name is set.
+     *
+     * Used internally by `resolveHologram` to stamp
+     * `_hologram.sourceHolonName` so every consumer of a resolved hologram
+     * already has the display name without a second round-trip.
+     */
+    async getHolonName(holonId) {
+        if (!holonId) return null;
+        const key = String(holonId);
+        if (this._holonNameCache.has(key)) return this._holonNameCache.get(key);
+        try {
+            const settings = await this.get(key, 'settings', key);
+            let name = null;
+            if (settings) {
+                if (Array.isArray(settings)) {
+                    const found = settings.find(s => s && typeof s.name === 'string' && s.name.trim() !== '');
+                    name = found ? found.name : null;
+                } else if (typeof settings.name === 'string' && settings.name.trim() !== '') {
+                    name = settings.name;
+                }
+            }
+            this._holonNameCache.set(key, name);
+            return name;
+        } catch {
+            this._holonNameCache.set(key, null);
+            return null;
+        }
+    }
+
     generateId() {
         return Utils.generateId();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holosphere",
-  "version": "1.3.0-alpha4",
+  "version": "1.3.0-alpha7",
   "description": "Holonic Geospatial Communication Infrastructure",
   "main": "holosphere.js",
   "module": "holosphere.js",

package/utils.js

@@ -44,13 +44,21 @@ export function getHolonScalespace(holon) { // Doesn't need holoInstance
 
 /**
  * Subscribes to changes in a specific holon and lens.
+ *
+ * Returns **synchronously** — the call has no internal awaits, so callers
+ * never need to `await` the result. (`await` on the return value still
+ * works as before; it just resolves through the value unchanged.) This
+ * means `const sub = holosphere.subscribe(...); sub.unsubscribe();` is the
+ * canonical pattern and there is no `Promise<{ unsubscribe }>` shape to
+ * disambiguate against the resolved object.
+ *
  * @param {HoloSphere} holoInstance - The HoloSphere instance.
  * @param {string} holon - The holon identifier.
  * @param {string} lens - The lens to subscribe to.
  * @param {function} callback - The callback to execute on changes.
- * @returns {Promise<object>} - Subscription object with unsubscribe method
+ * @returns {{ unsubscribe: () => void }} - Subscription with unsubscribe method.
  */
-export async function subscribe(holoInstance, holon, lens, callback) {
+export function subscribe(holoInstance, holon, lens, callback) {
     if (!holon || !lens) {
         throw new Error('subscribe: Missing holon or lens parameters:', holon, lens);
     }
@@ -82,6 +90,17 @@ export async function subscribe(holoInstance, holon, lens, callback) {
                         }
                     }
 
+                    // Subscribers expect `object | null`. `parse()` can return
+                    // a string/number/boolean when a legacy or corrupted leaf
+                    // happened to be a JSON-encoded primitive (e.g.
+                    // `'"hello"'` parses to `'hello'`). Drop those so every
+                    // consumer can stop guarding with
+                    // `typeof x === 'string' ? JSON.parse(x) : x`.
+                    if (parsed !== null && (typeof parsed !== 'object' || Array.isArray(parsed))) {
+                        console.warn(`[holosphere.subscribe] dropping non-object payload at ${holon}/${lens}/${key}:`, typeof parsed);
+                        return;
+                    }
+
                     // Check again if subscription ID still exists before calling callback
                     if (holoInstance.subscriptions[subscriptionId]) {
                         callback(parsed, key);
@@ -102,9 +121,14 @@ export async function subscribe(holoInstance, holon, lens, callback) {
             gunListener: gunListener  // Store the listener too (optional, maybe needed for close?)
         };
 
-        // Return an object with unsubscribe method
+        // Return an object with unsubscribe method.
+        // `unsubscribe` is sync — nothing it does (`mapChain.off()`,
+        // `delete subscriptions[id]`) blocks. Keeping it sync means the
+        // returned shape is `{ unsubscribe: () => void }` rather than
+        // `() => Promise<void>`, matching what callers expect when they
+        // store it in a `() => void` cleanup slot.
         return {
-            unsubscribe: async () => {
+            unsubscribe: () => {
                 const sub = holoInstance.subscriptions[subscriptionId];
                 if (!sub) {
                     return;
@@ -114,9 +138,7 @@ export async function subscribe(holoInstance, holon, lens, callback) {
                     // Turn off the Gun subscription using the stored mapChain reference
                     if (sub.mapChain) { // Check if mapChain exists
                         sub.mapChain.off(); // Call off() on the chain where .on() was attached
-                        // Optional: Add delay back? Let's omit for now.
-                        // await new Promise(res => setTimeout(res, 50));
-                    } // We might not need to call off() on gunListener explicitly
+                    }
 
                     // Remove from subscriptions object AFTER turning off listener
                     delete holoInstance.subscriptions[subscriptionId];