@git-stunts/git-warp 12.3.0 → 12.4.1

package/src/domain/warp/query.methods.js

@@ -311,10 +311,7 @@ export function query() {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} name - Observer name
- * @param {Object} config - Observer configuration
- * @param {string|string[]} config.match - Glob pattern(s) for visible nodes
- * @param {string[]} [config.expose] - Property keys to include
- * @param {string[]} [config.redact] - Property keys to exclude
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} config - Observer configuration
  * @returns {Promise<import('../services/ObserverView.js').default>} A read-only observer view
  */
 export async function observer(name, config) {
@@ -331,14 +328,8 @@ export async function observer(name, config) {
  * Computes the directed MDL translation cost from observer A to observer B.
  *
  * @this {import('../WarpGraph.js').default}
- * @param {Object} configA - Observer configuration for A
- * @param {string|string[]} configA.match - Glob pattern(s) for visible nodes
- * @param {string[]} [configA.expose] - Property keys to include
- * @param {string[]} [configA.redact] - Property keys to exclude
- * @param {Object} configB - Observer configuration for B
- * @param {string|string[]} configB.match - Glob pattern(s) for visible nodes
- * @param {string[]} [configB.expose] - Property keys to include
- * @param {string[]} [configB.redact] - Property keys to exclude
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} configA - Observer configuration for A
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} configB - Observer configuration for B
  * @returns {Promise<{cost: number, breakdown: {nodeLoss: number, edgeLoss: number, propLoss: number}}>}
  */
 export async function translationCost(configA, configB) {
@@ -368,12 +359,12 @@ export async function getContentOid(nodeId) {
 /**
  * Gets the content blob for a node, or null if none is attached.
  *
- * Returns the raw Buffer from `readBlob()`. Consumers wanting text
- * should call `.toString('utf8')` on the result.
+ * Returns the raw bytes from `readBlob()`. Consumers wanting text
+ * should decode the result with `new TextDecoder().decode(buf)`.
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} nodeId - The node ID to get content for
- * @returns {Promise<Buffer|null>} Content buffer or null
+ * @returns {Promise<Uint8Array|null>} Content bytes or null
  * @throws {Error} If the referenced blob OID is not in the object store
  *   (e.g., garbage-collected despite anchoring). Callers should handle this
  *   if operating on repos with aggressive GC or partial clones.
@@ -409,14 +400,14 @@ export async function getEdgeContentOid(from, to, label) {
 /**
  * Gets the content blob for an edge, or null if none is attached.
  *
- * Returns the raw Buffer from `readBlob()`. Consumers wanting text
- * should call `.toString('utf8')` on the result.
+ * Returns the raw bytes from `readBlob()`. Consumers wanting text
+ * should decode the result with `new TextDecoder().decode(buf)`.
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} from - Source node ID
  * @param {string} to - Target node ID
  * @param {string} label - Edge label
- * @returns {Promise<Buffer|null>} Content buffer or null
+ * @returns {Promise<Uint8Array|null>} Content bytes or null
  * @throws {Error} If the referenced blob OID is not in the object store
  *   (e.g., garbage-collected despite anchoring). Callers should handle this
  *   if operating on repos with aggressive GC or partial clones.

package/src/domain/warp/subscribe.methods.js

@@ -22,10 +22,7 @@ import { matchGlob } from '../utils/matchGlob.js';
  * One handler's error does not prevent other handlers from being called.
  *
  * @this {import('../WarpGraph.js').default}
- * @param {Object} options - Subscription options
- * @param {(diff: import('../services/StateDiff.js').StateDiffResult) => void} options.onChange - Called with diff when graph changes
- * @param {(error: Error) => void} [options.onError] - Called if onChange throws an error
- * @param {boolean} [options.replay=false] - If true, immediately fires onChange with initial state diff
+ * @param {{ onChange: (diff: import('../services/StateDiff.js').StateDiffResult) => void, onError?: (error: unknown) => void, replay?: boolean }} options - Subscription options
  * @returns {{unsubscribe: () => void}} Subscription handle
  * @throws {Error} If onChange is not a function
  *
@@ -103,10 +100,7 @@ export function subscribe({ onChange, onError, replay = false }) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string|string[]} pattern - Glob pattern(s) (e.g., 'user:*', 'order:123', '*')
- * @param {Object} options - Watch options
- * @param {(diff: import('../services/StateDiff.js').StateDiffResult) => void} options.onChange - Called with filtered diff when matching changes occur
- * @param {(error: Error) => void} [options.onError] - Called if onChange throws an error
- * @param {number} [options.poll] - Poll interval in ms (min 1000); checks frontier and auto-materializes
+ * @param {{ onChange: (diff: import('../services/StateDiff.js').StateDiffResult) => void, onError?: (error: unknown) => void, poll?: number }} options - Watch options
  * @returns {{unsubscribe: () => void}} Subscription handle
  * @throws {Error} If pattern is not a string or array of strings
  * @throws {Error} If onChange is not a function

package/src/globals.d.ts

@@ -62,3 +62,10 @@ interface BunServeOptions {
 declare namespace Bun {
   function serve(options: BunServeOptions): BunServer;
 }
+
+/* ------------------------------------------------------------------ */
+/*  globalThis augmentation                                           */
+/* ------------------------------------------------------------------ */
+
+declare var Bun: typeof Bun | undefined;
+declare var Deno: typeof Deno | undefined;

package/src/infrastructure/adapters/BunHttpAdapter.js

@@ -96,8 +96,8 @@ function toResponse(portResponse) {
  * Creates the Bun fetch handler that bridges between Request/Response
  * and the HttpServerPort plain-object contract.
  *
- * @param {Function} requestHandler - Port-style async handler
- * @param {{ error: Function }} logger
+ * @param {(request: import('../../ports/HttpServerPort.js').HttpRequest) => Promise<import('../../ports/HttpServerPort.js').HttpResponse>} requestHandler - Port-style async handler
+ * @param {{ error: (...args: unknown[]) => void }} logger
  * @returns {(request: Request) => Promise<Response>}
  */
 function createFetchHandler(requestHandler, logger) {
@@ -125,10 +125,6 @@ function createFetchHandler(requestHandler, logger) {
   };
 }
 
-/**
- * @typedef {{ hostname: string, port: number, stop: (closeActiveConnections?: boolean) => Promise<void> }} BunServer
- */
-
 /**
  * Starts a Bun server and invokes the callback with (null) on success
  * or (err) on failure.
@@ -137,7 +133,7 @@ function createFetchHandler(requestHandler, logger) {
  * (unlike Node's server.listen which defers via the event loop).
  *
  * @param {BunServeOptions} serveOptions
- * @param {Function|undefined} cb - Node-style callback
+ * @param {((err: Error | null) => void) | undefined} cb - Node-style callback
  * @returns {BunServer} The Bun server instance
  */
 function startServer(serveOptions, cb) {
@@ -152,7 +148,7 @@ function startServer(serveOptions, cb) {
  * Safely stops a Bun server, forwarding errors to the callback.
  *
  * @param {{ server: BunServer | null }} state - Shared mutable state
- * @param {Function} [callback]
+ * @param {(err?: Error) => void} [callback]
  */
 function stopServer(state, callback) {
   try {
@@ -165,9 +161,9 @@ function stopServer(state, callback) {
     if (callback) {
       callback();
     }
-  } catch (err) {
+  } catch (/** @type {unknown} */ err) {
     if (callback) {
-      callback(err);
+      callback(err instanceof Error ? err : new Error(String(err)));
     }
   }
 }
@@ -184,7 +180,7 @@ const noopLogger = { error() {} };
  */
 export default class BunHttpAdapter extends HttpServerPort {
   /**
-   * @param {{ logger?: { error: Function } }} [options]
+   * @param {{ logger?: { error: (...args: unknown[]) => void } }} [options]
    */
   constructor({ logger } = {}) {
     super();
@@ -192,8 +188,8 @@ export default class BunHttpAdapter extends HttpServerPort {
   }
 
   /**
-   * @param {Function} requestHandler
-   * @returns {{ listen: Function, close: Function, address: Function }}
+   * @param {(request: import('../../ports/HttpServerPort.js').HttpRequest) => Promise<import('../../ports/HttpServerPort.js').HttpResponse>} requestHandler
+   * @returns {import('../../ports/HttpServerPort.js').HttpServerHandle}
    */
   createServer(requestHandler) {
     const fetchHandler = createFetchHandler(requestHandler, this._logger);
@@ -203,8 +199,8 @@ export default class BunHttpAdapter extends HttpServerPort {
     return {
       /**
        * @param {number} port
-       * @param {string|Function} [host]
-       * @param {Function} [callback]
+       * @param {string|((err?: Error | null) => void)} [host]
+       * @param {(err?: Error | null) => void} [callback]
        */
       listen(port, host, callback) {
         const cb = typeof host === 'function' ? host : callback;
@@ -218,14 +214,14 @@ export default class BunHttpAdapter extends HttpServerPort {
 
         try {
           state.server = startServer(serveOptions, cb);
-        } catch (err) {
+        } catch (/** @type {unknown} */ err) {
           if (cb) {
-            cb(err);
+            cb(err instanceof Error ? err : new Error(String(err)));
           }
         }
       },
 
-      /** @param {Function} [callback] */
+      /** @param {(err?: Error) => void} [callback] */
       close: (callback) => stopServer(state, callback),
 
       address() {

package/src/infrastructure/adapters/ConsoleLogger.js

@@ -46,10 +46,7 @@ const LEVEL_NAMES = Object.freeze({
 export default class ConsoleLogger extends LoggerPort {
   /**
    * Creates a new ConsoleLogger instance.
-   * @param {Object} [options] - Logger options
-   * @param {number} [options.level=LogLevel.INFO] - Minimum log level to output
-   * @param {Record<string, unknown>} [options.context={}] - Base context for all log entries
-   * @param {function(): string} [options.timestampFn] - Custom timestamp function (defaults to ISO string)
+   * @param {{ level?: number | string, context?: Record<string, unknown>, timestampFn?: function(): string }} [options] - Logger options
    */
   constructor({ level = LogLevel.INFO, context = {}, timestampFn } = {}) {
     super();
@@ -114,11 +111,7 @@ export default class ConsoleLogger extends LoggerPort {
 
   /**
    * Internal logging implementation.
-   * @param {Object} opts - Log options
-   * @param {number} opts.level - Numeric log level
-   * @param {string} opts.levelName - String representation of level
-   * @param {string} opts.message - Log message
-   * @param {Record<string, unknown>} [opts.context] - Additional context
+   * @param {{ level: number, levelName: string, message: string, context?: Record<string, unknown> }} opts - Log options
    * @private
    */
   _log({ level, levelName, message, context }) {

package/src/infrastructure/adapters/DenoHttpAdapter.js

@@ -90,8 +90,8 @@ function toDenoResponse(plain) {
  * Creates a Deno.serve-compatible handler that bridges to the
  * HttpServerPort request handler contract.
  *
- * @param {Function} requestHandler
- * @param {{ error: Function }} logger
+ * @param {(request: import('../../ports/HttpServerPort.js').HttpRequest) => Promise<import('../../ports/HttpServerPort.js').HttpResponse>} requestHandler
+ * @param {{ error: (...args: unknown[]) => void }} logger
  * @returns {(request: Request) => Promise<Response>}
  */
 function createHandler(requestHandler, logger) {
@@ -123,8 +123,8 @@ function createHandler(requestHandler, logger) {
 /**
  * Gracefully shuts down the Deno HTTP server.
  *
- * @param {{ server: *}} state - Shared mutable state `{ server }`
- * @param {Function} [callback]
+ * @param {{ server: { shutdown: () => Promise<void> } | null }} state - Shared mutable state `{ server }`
+ * @param {(err?: Error) => void} [callback]
  */
 function closeImpl(state, callback) {
   if (!state.server) {
@@ -143,7 +143,7 @@ function closeImpl(state, callback) {
     /** @param {unknown} err */ (err) => {
       state.server = null;
       if (callback) {
-        callback(err);
+        callback(err instanceof Error ? err : new Error(String(err)));
       }
     }
   );
@@ -152,7 +152,7 @@ function closeImpl(state, callback) {
 /**
  * Returns the server's bound address info.
  *
- * @param {{ server: * }} state - Shared mutable state `{ server }`
+ * @param {{ server: { addr: { transport: string, hostname: string, port: number } } | null }} state - Shared mutable state `{ server }`
  * @returns {{ address: string, port: number, family: string }|null}
  */
 function addressImpl(state) {
@@ -183,7 +183,7 @@ const noopLogger = { error() {} };
  */
 export default class DenoHttpAdapter extends HttpServerPort {
   /**
-   * @param {{ logger?: { error: Function } }} [options]
+   * @param {{ logger?: { error: (...args: unknown[]) => void } }} [options]
    */
   constructor({ logger } = {}) {
     super();
@@ -191,19 +191,19 @@ export default class DenoHttpAdapter extends HttpServerPort {
   }
 
   /**
-   * @param {Function} requestHandler
-   * @returns {{ listen: Function, close: Function, address: Function }}
+   * @param {(request: import('../../ports/HttpServerPort.js').HttpRequest) => Promise<import('../../ports/HttpServerPort.js').HttpResponse>} requestHandler
+   * @returns {import('../../ports/HttpServerPort.js').HttpServerHandle}
    */
   createServer(requestHandler) {
     const handler = createHandler(requestHandler, this._logger);
-    /** @type {{ server: * }} */
+    /** @type {{ server: { shutdown: () => Promise<void>, addr: { transport: string, hostname: string, port: number } } | null }} */
     const state = { server: null };
 
     return {
       /**
        * @param {number} port
-       * @param {string|Function} [host]
-       * @param {Function} [callback]
+       * @param {string|((err?: Error | null) => void)} [host]
+       * @param {(err?: Error | null) => void} [callback]
        */
       listen: (port, host, callback) => {
         const cb = typeof host === 'function' ? host : callback;
@@ -224,15 +224,15 @@ export default class DenoHttpAdapter extends HttpServerPort {
           }
 
           state.server = globalThis.Deno.serve(serveOptions, handler);
-        } catch (err) {
+        } catch (/** @type {unknown} */ err) {
           if (cb) {
-            cb(err);
+            cb(err instanceof Error ? err : new Error(String(err)));
           } else {
             throw err;
           }
         }
       },
-      /** @param {Function} [callback] */
+      /** @param {(err?: Error) => void} [callback] */
       close: (callback) => {
         closeImpl(state, callback);
       },