@zero-server/sdk 0.9.0 → 0.9.2

package/lib/grpc/status.js

@@ -1,118 +1,118 @@
-/**
- * @module grpc/status
- * @description Standard gRPC status codes (as defined by the gRPC specification).
- *              Each code has a numeric value, a name, and a human-readable description.
- *              Used by both server and client to communicate call outcomes via trailers.
- *
- * @see https://grpc.github.io/grpc/core/md_doc_statuscodes.html
- */
-
-const log = require('../debug')('zero:grpc');
-
-// -- Status Codes ------------------------------------------
-
-/**
- * gRPC status code enum. Mirrors the canonical codes from the gRPC spec.
- *
- * @enum {number}
- *
- * @example
- *   const { GrpcStatus } = require('@zero-server/sdk');
- *   call.sendError(GrpcStatus.NOT_FOUND, 'User not found');
- */
-const GrpcStatus = {
-    /** The operation completed successfully. */
-    OK: 0,
-    /** The operation was cancelled (typically by the caller). */
-    CANCELLED: 1,
-    /** Unknown error — a catch-all for unexpected failures. */
-    UNKNOWN: 2,
-    /** The client specified an invalid argument. */
-    INVALID_ARGUMENT: 3,
-    /** The deadline expired before the operation could complete. */
-    DEADLINE_EXCEEDED: 4,
-    /** The requested entity was not found. */
-    NOT_FOUND: 5,
-    /** The entity that a client attempted to create already exists. */
-    ALREADY_EXISTS: 6,
-    /** The caller does not have permission to execute the operation. */
-    PERMISSION_DENIED: 7,
-    /** Some resource has been exhausted (e.g. quota, disk space). */
-    RESOURCE_EXHAUSTED: 8,
-    /** The operation was rejected because the system is not in a required state. */
-    FAILED_PRECONDITION: 9,
-    /** The operation was aborted, typically due to a concurrency conflict. */
-    ABORTED: 10,
-    /** The operation was attempted past the valid range. */
-    OUT_OF_RANGE: 11,
-    /** The operation is not implemented or not supported. */
-    UNIMPLEMENTED: 12,
-    /** Internal error — invariants expected by the server have been broken. */
-    INTERNAL: 13,
-    /** The service is currently unavailable, usually a transient condition. */
-    UNAVAILABLE: 14,
-    /** Unrecoverable data loss or corruption. */
-    DATA_LOSS: 15,
-    /** The request does not have valid authentication credentials. */
-    UNAUTHENTICATED: 16,
-};
-
-/**
- * Reverse lookup: number → string name.
- * @type {Object<number, string>}
- */
-const STATUS_NAMES = {};
-for (const [name, code] of Object.entries(GrpcStatus))
-{
-    STATUS_NAMES[code] = name;
-}
-
-/**
- * Map gRPC status code to the appropriate HTTP/2 status code for trailers-only responses.
- *
- * @param {number} grpcCode - gRPC status code.
- * @returns {number} Corresponding HTTP status code.
- */
-function grpcToHttp(grpcCode)
-{
-    switch (grpcCode)
-    {
-        case GrpcStatus.OK: return 200;
-        case GrpcStatus.INVALID_ARGUMENT: return 400;
-        case GrpcStatus.FAILED_PRECONDITION: return 400;
-        case GrpcStatus.OUT_OF_RANGE: return 400;
-        case GrpcStatus.UNAUTHENTICATED: return 401;
-        case GrpcStatus.PERMISSION_DENIED: return 403;
-        case GrpcStatus.NOT_FOUND: return 404;
-        case GrpcStatus.ALREADY_EXISTS: return 409;
-        case GrpcStatus.ABORTED: return 409;
-        case GrpcStatus.RESOURCE_EXHAUSTED: return 429;
-        case GrpcStatus.CANCELLED: return 499;
-        case GrpcStatus.UNIMPLEMENTED: return 501;
-        case GrpcStatus.UNAVAILABLE: return 503;
-        case GrpcStatus.DEADLINE_EXCEEDED: return 504;
-        case GrpcStatus.UNKNOWN:
-        case GrpcStatus.INTERNAL:
-        case GrpcStatus.DATA_LOSS:
-        default:
-            return 500;
-    }
-}
-
-/**
- * Get the human-readable name for a gRPC status code.
- *
- * @param {number} code - gRPC status code.
- * @returns {string} Status name or 'UNKNOWN'.
- */
-function statusName(code)
-{
-    return STATUS_NAMES[code] || 'UNKNOWN';
-}
-
-module.exports = {
-    GrpcStatus,
-    STATUS_NAMES,
-    grpcToHttp,
-    statusName,
-};
+/**
+ * @module grpc/status
+ * @description Standard gRPC status codes (as defined by the gRPC specification).
+ *              Each code has a numeric value, a name, and a human-readable description.
+ *              Used by both server and client to communicate call outcomes via trailers.
+ *
+ * @see https://grpc.github.io/grpc/core/md_doc_statuscodes.html
+ */
+
+const log = require('../debug')('zero:grpc');
+
+// -- Status Codes ------------------------------------------
+
+/**
+ * gRPC status code enum. Mirrors the canonical codes from the gRPC spec.
+ *
+ * @enum {number}
+ *
+ * @example
+ *   const { GrpcStatus } = require('@zero-server/sdk');
+ *   call.sendError(GrpcStatus.NOT_FOUND, 'User not found');
+ */
+const GrpcStatus = {
+    /** The operation completed successfully. */
+    OK: 0,
+    /** The operation was cancelled (typically by the caller). */
+    CANCELLED: 1,
+    /** Unknown error — a catch-all for unexpected failures. */
+    UNKNOWN: 2,
+    /** The client specified an invalid argument. */
+    INVALID_ARGUMENT: 3,
+    /** The deadline expired before the operation could complete. */
+    DEADLINE_EXCEEDED: 4,
+    /** The requested entity was not found. */
+    NOT_FOUND: 5,
+    /** The entity that a client attempted to create already exists. */
+    ALREADY_EXISTS: 6,
+    /** The caller does not have permission to execute the operation. */
+    PERMISSION_DENIED: 7,
+    /** Some resource has been exhausted (e.g. quota, disk space). */
+    RESOURCE_EXHAUSTED: 8,
+    /** The operation was rejected because the system is not in a required state. */
+    FAILED_PRECONDITION: 9,
+    /** The operation was aborted, typically due to a concurrency conflict. */
+    ABORTED: 10,
+    /** The operation was attempted past the valid range. */
+    OUT_OF_RANGE: 11,
+    /** The operation is not implemented or not supported. */
+    UNIMPLEMENTED: 12,
+    /** Internal error — invariants expected by the server have been broken. */
+    INTERNAL: 13,
+    /** The service is currently unavailable, usually a transient condition. */
+    UNAVAILABLE: 14,
+    /** Unrecoverable data loss or corruption. */
+    DATA_LOSS: 15,
+    /** The request does not have valid authentication credentials. */
+    UNAUTHENTICATED: 16,
+};
+
+/**
+ * Reverse lookup: number → string name.
+ * @type {Object<number, string>}
+ */
+const STATUS_NAMES = {};
+for (const [name, code] of Object.entries(GrpcStatus))
+{
+    STATUS_NAMES[code] = name;
+}
+
+/**
+ * Map gRPC status code to the appropriate HTTP/2 status code for trailers-only responses.
+ *
+ * @param {number} grpcCode - gRPC status code.
+ * @returns {number} Corresponding HTTP status code.
+ */
+function grpcToHttp(grpcCode)
+{
+    switch (grpcCode)
+    {
+        case GrpcStatus.OK: return 200;
+        case GrpcStatus.INVALID_ARGUMENT: return 400;
+        case GrpcStatus.FAILED_PRECONDITION: return 400;
+        case GrpcStatus.OUT_OF_RANGE: return 400;
+        case GrpcStatus.UNAUTHENTICATED: return 401;
+        case GrpcStatus.PERMISSION_DENIED: return 403;
+        case GrpcStatus.NOT_FOUND: return 404;
+        case GrpcStatus.ALREADY_EXISTS: return 409;
+        case GrpcStatus.ABORTED: return 409;
+        case GrpcStatus.RESOURCE_EXHAUSTED: return 429;
+        case GrpcStatus.CANCELLED: return 499;
+        case GrpcStatus.UNIMPLEMENTED: return 501;
+        case GrpcStatus.UNAVAILABLE: return 503;
+        case GrpcStatus.DEADLINE_EXCEEDED: return 504;
+        case GrpcStatus.UNKNOWN:
+        case GrpcStatus.INTERNAL:
+        case GrpcStatus.DATA_LOSS:
+        default:
+            return 500;
+    }
+}
+
+/**
+ * Get the human-readable name for a gRPC status code.
+ *
+ * @param {number} code - gRPC status code.
+ * @returns {string} Status name or 'UNKNOWN'.
+ */
+function statusName(code)
+{
+    return STATUS_NAMES[code] || 'UNKNOWN';
+}
+
+module.exports = {
+    GrpcStatus,
+    STATUS_NAMES,
+    grpcToHttp,
+    statusName,
+};

package/lib/grpc/watch.js

@@ -1,173 +1,173 @@
-/**
- * @module grpc/watch
- * @description Proto file hot-reload for development.
- *              Watches `.proto` files for changes using `fs.watch()` and
- *              re-parses/re-registers gRPC services automatically.
- *
- *              **Dev-only** — disabled by default when `NODE_ENV=production`.
- *
- * @example
- *   const { createApp, watchProto } = require('@zero-server/sdk');
- *   const app = createApp();
- *
- *   watchProto(app, './protos/greeter.proto', 'Greeter', handlers, {
- *       onReload: (schema) => console.log('Reloaded!'),
- *   });
- *
- *   app.listen(50051, { http2: true });
- */
-
-const fs = require('fs');
-const path = require('path');
-const log = require('../debug')('zero:grpc:watch');
-
-// Lazy-load proto parser
-let _parseProtoFile = null;
-function _getParser()
-{
-    if (!_parseProtoFile) _parseProtoFile = require('./proto').parseProtoFile;
-    return _parseProtoFile;
-}
-
-// -- Constants ---------------------------------------------------
-
-const DEFAULT_DEBOUNCE = 300; // ms
-
-// -- watchProto --------------------------------------------------
-
-/**
- * Watch a `.proto` file and hot-reload the gRPC service on changes.
- * Parses the file, registers the service, then watches for modifications.
- *
- * Disabled in production unless `opts.production` is `true`.
- *
- * @param {object} app - The zero-server App instance.
- * @param {string} protoPath - Path to the `.proto` file.
- * @param {string} serviceName - Service name to register.
- * @param {Object<string, Function>} handlers - Method handlers map.
- * @param {object} [opts] - Options.
- * @param {Function[]} [opts.interceptors] - Per-service interceptors.
- * @param {number} [opts.maxMessageSize] - Max incoming message size.
- * @param {boolean} [opts.compress=false] - Compress outgoing messages.
- * @param {number} [opts.debounce=300] - Debounce interval in ms.
- * @param {boolean} [opts.production=false] - Allow in production.
- * @param {Function} [opts.onReload] - `(schema) => void` callback after reload.
- * @param {Function} [opts.onError] - `(err) => void` callback on parse/reload error.
- * @returns {{ stop: () => void, schema: object }} Controller with `stop()` and current schema.
- *
- * @example
- *   const watcher = watchProto(app, './hello.proto', 'Greeter', {
- *       SayHello(call) { return { message: 'Hello ' + call.request.name }; },
- *   });
- *   // Later: watcher.stop();
- */
-function watchProto(app, protoPath, serviceName, handlers, opts = {})
-{
-    if (!opts.production && process.env.NODE_ENV === 'production')
-    {
-        log.warn('watchProto disabled in production (set { production: true } to override)');
-        // Still do an initial load
-        const parseProtoFile = _getParser();
-        const schema = parseProtoFile(protoPath);
-        app.grpc(schema, serviceName, handlers, opts);
-        return { stop() {}, schema };
-    }
-
-    const debounceMs = opts.debounce || DEFAULT_DEBOUNCE;
-    const resolvedPath = path.resolve(protoPath);
-
-    const parseProtoFile = _getParser();
-    let currentSchema = null;
-
-    // Initial load
-    try
-    {
-        currentSchema = parseProtoFile(resolvedPath);
-        app.grpc(currentSchema, serviceName, handlers, opts);
-        log.info('proto loaded: %s → %s', resolvedPath, serviceName);
-    }
-    catch (err)
-    {
-        log.error('initial proto parse failed: %s', err.message);
-        if (typeof opts.onError === 'function') opts.onError(err);
-        else throw err;
-    }
-
-    // Debounced reload
-    let debounceTimer = null;
-
-    function _reload()
-    {
-        try
-        {
-            const schema = parseProtoFile(resolvedPath);
-
-            // Verify the service still exists in the schema
-            if (!schema.services[serviceName])
-            {
-                const err = new Error(`Service "${serviceName}" not found after reload`);
-                log.error(err.message);
-                if (typeof opts.onError === 'function') opts.onError(err);
-                return;
-            }
-
-            // Re-register: the grpc registry replaces the existing service entry
-            if (app._grpcRegistry)
-            {
-                app._grpcRegistry.addService(schema, serviceName, handlers, opts);
-            }
-
-            currentSchema = schema;
-            log.info('proto reloaded: %s', resolvedPath);
-
-            if (typeof opts.onReload === 'function') opts.onReload(schema);
-        }
-        catch (err)
-        {
-            log.error('proto reload failed: %s', err.message);
-            if (typeof opts.onError === 'function') opts.onError(err);
-        }
-    }
-
-    // Watch the file
-    let watcher;
-    try
-    {
-        watcher = fs.watch(resolvedPath, (eventType) =>
-        {
-            if (eventType !== 'change') return;
-
-            if (debounceTimer) clearTimeout(debounceTimer);
-            debounceTimer = setTimeout(_reload, debounceMs);
-        });
-
-        watcher.on('error', (err) =>
-        {
-            log.error('fs.watch error: %s', err.message);
-            if (typeof opts.onError === 'function') opts.onError(err);
-        });
-
-        log.info('watching proto file: %s', resolvedPath);
-    }
-    catch (err)
-    {
-        log.error('failed to watch proto file: %s', err.message);
-        if (typeof opts.onError === 'function') opts.onError(err);
-    }
-
-    return {
-        stop()
-        {
-            if (debounceTimer) clearTimeout(debounceTimer);
-            if (watcher) watcher.close();
-            log.info('stopped watching: %s', resolvedPath);
-        },
-        get schema() { return currentSchema; },
-    };
-}
-
-// -- Exports -------------------------------------------------
-
-module.exports = {
-    watchProto,
-};
+/**
+ * @module grpc/watch
+ * @description Proto file hot-reload for development.
+ *              Watches `.proto` files for changes using `fs.watch()` and
+ *              re-parses/re-registers gRPC services automatically.
+ *
+ *              **Dev-only** — disabled by default when `NODE_ENV=production`.
+ *
+ * @example
+ *   const { createApp, watchProto } = require('@zero-server/sdk');
+ *   const app = createApp();
+ *
+ *   watchProto(app, './protos/greeter.proto', 'Greeter', handlers, {
+ *       onReload: (schema) => console.log('Reloaded!'),
+ *   });
+ *
+ *   app.listen(50051, { http2: true });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const log = require('../debug')('zero:grpc:watch');
+
+// Lazy-load proto parser
+let _parseProtoFile = null;
+function _getParser()
+{
+    if (!_parseProtoFile) _parseProtoFile = require('./proto').parseProtoFile;
+    return _parseProtoFile;
+}
+
+// -- Constants ---------------------------------------------------
+
+const DEFAULT_DEBOUNCE = 300; // ms
+
+// -- watchProto --------------------------------------------------
+
+/**
+ * Watch a `.proto` file and hot-reload the gRPC service on changes.
+ * Parses the file, registers the service, then watches for modifications.
+ *
+ * Disabled in production unless `opts.production` is `true`.
+ *
+ * @param {object} app - The zero-server App instance.
+ * @param {string} protoPath - Path to the `.proto` file.
+ * @param {string} serviceName - Service name to register.
+ * @param {Object<string, Function>} handlers - Method handlers map.
+ * @param {object} [opts] - Options.
+ * @param {Function[]} [opts.interceptors] - Per-service interceptors.
+ * @param {number} [opts.maxMessageSize] - Max incoming message size.
+ * @param {boolean} [opts.compress=false] - Compress outgoing messages.
+ * @param {number} [opts.debounce=300] - Debounce interval in ms.
+ * @param {boolean} [opts.production=false] - Allow in production.
+ * @param {Function} [opts.onReload] - `(schema) => void` callback after reload.
+ * @param {Function} [opts.onError] - `(err) => void` callback on parse/reload error.
+ * @returns {{ stop: () => void, schema: object }} Controller with `stop()` and current schema.
+ *
+ * @example
+ *   const watcher = watchProto(app, './hello.proto', 'Greeter', {
+ *       SayHello(call) { return { message: 'Hello ' + call.request.name }; },
+ *   });
+ *   // Later: watcher.stop();
+ */
+function watchProto(app, protoPath, serviceName, handlers, opts = {})
+{
+    if (!opts.production && process.env.NODE_ENV === 'production')
+    {
+        log.warn('watchProto disabled in production (set { production: true } to override)');
+        // Still do an initial load
+        const parseProtoFile = _getParser();
+        const schema = parseProtoFile(protoPath);
+        app.grpc(schema, serviceName, handlers, opts);
+        return { stop() {}, schema };
+    }
+
+    const debounceMs = opts.debounce || DEFAULT_DEBOUNCE;
+    const resolvedPath = path.resolve(protoPath);
+
+    const parseProtoFile = _getParser();
+    let currentSchema = null;
+
+    // Initial load
+    try
+    {
+        currentSchema = parseProtoFile(resolvedPath);
+        app.grpc(currentSchema, serviceName, handlers, opts);
+        log.info('proto loaded: %s → %s', resolvedPath, serviceName);
+    }
+    catch (err)
+    {
+        log.error('initial proto parse failed: %s', err.message);
+        if (typeof opts.onError === 'function') opts.onError(err);
+        else throw err;
+    }
+
+    // Debounced reload
+    let debounceTimer = null;
+
+    function _reload()
+    {
+        try
+        {
+            const schema = parseProtoFile(resolvedPath);
+
+            // Verify the service still exists in the schema
+            if (!schema.services[serviceName])
+            {
+                const err = new Error(`Service "${serviceName}" not found after reload`);
+                log.error(err.message);
+                if (typeof opts.onError === 'function') opts.onError(err);
+                return;
+            }
+
+            // Re-register: the grpc registry replaces the existing service entry
+            if (app._grpcRegistry)
+            {
+                app._grpcRegistry.addService(schema, serviceName, handlers, opts);
+            }
+
+            currentSchema = schema;
+            log.info('proto reloaded: %s', resolvedPath);
+
+            if (typeof opts.onReload === 'function') opts.onReload(schema);
+        }
+        catch (err)
+        {
+            log.error('proto reload failed: %s', err.message);
+            if (typeof opts.onError === 'function') opts.onError(err);
+        }
+    }
+
+    // Watch the file
+    let watcher;
+    try
+    {
+        watcher = fs.watch(resolvedPath, (eventType) =>
+        {
+            if (eventType !== 'change') return;
+
+            if (debounceTimer) clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(_reload, debounceMs);
+        });
+
+        watcher.on('error', (err) =>
+        {
+            log.error('fs.watch error: %s', err.message);
+            if (typeof opts.onError === 'function') opts.onError(err);
+        });
+
+        log.info('watching proto file: %s', resolvedPath);
+    }
+    catch (err)
+    {
+        log.error('failed to watch proto file: %s', err.message);
+        if (typeof opts.onError === 'function') opts.onError(err);
+    }
+
+    return {
+        stop()
+        {
+            if (debounceTimer) clearTimeout(debounceTimer);
+            if (watcher) watcher.close();
+            log.info('stopped watching: %s', resolvedPath);
+        },
+        get schema() { return currentSchema; },
+    };
+}
+
+// -- Exports -------------------------------------------------
+
+module.exports = {
+    watchProto,
+};

package/lib/http/index.js

@@ -1,10 +1,10 @@
-/**
- * @module http
- * @description HTTP request/response wrappers for zero-server.
- *              Exports Request and Response classes.
- */
-const Request = require('./request');
-const { compileTrust } = require('./request');
-const Response = require('./response');
-
-module.exports = { Request, Response, compileTrust };
+/**
+ * @module http
+ * @description HTTP request/response wrappers for zero-server.
+ *              Exports Request and Response classes.
+ */
+const Request = require('./request');
+const { compileTrust } = require('./request');
+const Response = require('./response');
+
+module.exports = { Request, Response, compileTrust };