@zlink-systems/framework-codec-protobuf 0.10.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 ZLink Systems
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/dist/browser/index.d.ts

@@ -0,0 +1,26 @@
+import type { ZlinkStreamEncodedPayload, ZlinkStreamPayloadCodec } from '@zlink-systems/stream-connector';
+export declare const ZLINK_PROTOBUF_CONTENT_TYPE = "application/x-protobuf";
+export declare const zlinkStreamProtobufCodecName = "protobuf";
+export interface ProtobufType<T> {
+    encode(message: T): {
+        finish(): Uint8Array;
+    };
+    decode(reader: Uint8Array): T;
+}
+export interface ProtobufEnvelopeCodecOptions {
+    encode(payload: unknown, context?: ProtobufEncodeContext | Function): ZlinkStreamEncodedPayload;
+    decode<TPayload = unknown>(payload: ZlinkStreamEncodedPayload): TPayload;
+}
+export type ProtobufMessageDirection = 'Request' | 'Response' | 'Error' | 'Send';
+export interface ProtobufEncodeContext {
+    readonly messageType?: Function;
+    readonly packetName?: string;
+    readonly direction: ProtobufMessageDirection;
+}
+export type ZlinkStreamProtobufEnvelopeCodec = ZlinkStreamPayloadCodec & {
+    encode(payload: unknown, context?: ProtobufEncodeContext | Function): ZlinkStreamEncodedPayload;
+};
+export declare function createZlinkStreamProtobufCodec<T>(type: ProtobufType<T>): ZlinkStreamPayloadCodec;
+export declare function createZlinkStreamProtobufEnvelopeCodec(options: ProtobufEnvelopeCodecOptions): ZlinkStreamProtobufEnvelopeCodec;
+export declare function toProto<T>(value: T, type: ProtobufType<T>, messageType?: Function): ZlinkStreamEncodedPayload;
+export declare function fromProto<T>(payload: ZlinkStreamEncodedPayload, type: ProtobufType<T>): T;

package/dist/browser/index.mjs

@@ -0,0 +1,57 @@
+// packages/stream-wire/src/lz4-pickle.ts
+var defaultMaxDecompressedPayloadSize = 64 * 1024;
+
+// packages/framework-codec-protobuf/src/index.ts
+var ZLINK_PROTOBUF_CONTENT_TYPE = "application/x-protobuf";
+var zlinkStreamProtobufCodecName = "protobuf";
+function createZlinkStreamProtobufCodec(type) {
+  return {
+    encode(payload, messageType) {
+      return toProto(payload, type, messageType);
+    },
+    decode(payload) {
+      return fromProto(payload, type);
+    }
+  };
+}
+function createZlinkStreamProtobufEnvelopeCodec(options) {
+  return {
+    encode(payload, context) {
+      return options.encode(payload, context);
+    },
+    decode(payload) {
+      return options.decode(payload);
+    }
+  };
+}
+function toProto(value, type, messageType) {
+  return {
+    codec: 3 /* Protobuf */,
+    payload: type.encode(value).finish(),
+    messageType: messageType ?? inferMessageType(value)
+  };
+}
+function fromProto(payload, type) {
+  ensureProtobuf(payload);
+  return type.decode(payload.payload);
+}
+function ensureProtobuf(payload) {
+  if (payload.codec !== 3 /* Protobuf */) {
+    throw new Error(`Stream payload codec is ${payload.codec}, not Protobuf.`);
+  }
+}
+function inferMessageType(value) {
+  if (value === null || value === void 0) {
+    return void 0;
+  }
+  const constructor = value.constructor;
+  return constructor === Object ? void 0 : constructor;
+}
+export {
+  ZLINK_PROTOBUF_CONTENT_TYPE,
+  createZlinkStreamProtobufCodec,
+  createZlinkStreamProtobufEnvelopeCodec,
+  fromProto,
+  toProto,
+  zlinkStreamProtobufCodecName
+};

package/dist/framework.d.ts

@@ -0,0 +1,12 @@
+import { type ZLinkCodecExtension, type ZLinkMessageSerializer } from '@zlink-systems/framework';
+import type { ZlinkStreamEncodedPayload, ZlinkStreamPayloadCodec } from '@zlink-systems/stream-connector';
+import { type ProtobufEncodeContext, type ProtobufEnvelopeCodecOptions } from './index';
+export { ZLINK_PROTOBUF_CONTENT_TYPE } from './index';
+export type ZLinkProtobufCodecExtension = ZLinkCodecExtension & ZlinkStreamPayloadCodec;
+export type ZLinkProtobufEnvelopeCodecExtension = ZLinkProtobufCodecExtension & {
+    encode(payload: unknown, context?: ProtobufEncodeContext | Function): ZlinkStreamEncodedPayload;
+};
+export declare function zlinkProtobufCodec(): ZLinkProtobufCodecExtension;
+export declare function createProtobufMessageSerializer(): ZLinkMessageSerializer;
+export declare function createZlinkProtobufEnvelopeCodec(options: ProtobufEnvelopeCodecOptions): ZLinkProtobufEnvelopeCodecExtension;
+export declare function createProtobufEnvelopeMessageSerializer(options: ProtobufEnvelopeCodecOptions): ZLinkMessageSerializer;

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import type { ZlinkStreamEncodedPayload, ZlinkStreamPayloadCodec } from '@zlink-systems/stream-connector';
+export declare const ZLINK_PROTOBUF_CONTENT_TYPE = "application/x-protobuf";
+export declare const zlinkStreamProtobufCodecName = "protobuf";
+export interface ProtobufType<T> {
+    encode(message: T): {
+        finish(): Uint8Array;
+    };
+    decode(reader: Uint8Array): T;
+}
+export interface ProtobufEnvelopeCodecOptions {
+    encode(payload: unknown, context?: ProtobufEncodeContext | Function): ZlinkStreamEncodedPayload;
+    decode<TPayload = unknown>(payload: ZlinkStreamEncodedPayload): TPayload;
+}
+export type ProtobufMessageDirection = 'Request' | 'Response' | 'Error' | 'Send';
+export interface ProtobufEncodeContext {
+    readonly messageType?: Function;
+    readonly packetName?: string;
+    readonly direction: ProtobufMessageDirection;
+}
+export type ZlinkStreamProtobufEnvelopeCodec = ZlinkStreamPayloadCodec & {
+    encode(payload: unknown, context?: ProtobufEncodeContext | Function): ZlinkStreamEncodedPayload;
+};
+export declare function createZlinkStreamProtobufCodec<T>(type: ProtobufType<T>): ZlinkStreamPayloadCodec;
+export declare function createZlinkStreamProtobufEnvelopeCodec(options: ProtobufEnvelopeCodecOptions): ZlinkStreamProtobufEnvelopeCodec;
+export declare function toProto<T>(value: T, type: ProtobufType<T>, messageType?: Function): ZlinkStreamEncodedPayload;
+export declare function fromProto<T>(payload: ZlinkStreamEncodedPayload, type: ProtobufType<T>): T;

package/dist/server/framework.cjs

@@ -0,0 +1,323 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/framework-codec-protobuf/src/framework.ts
+var framework_exports = {};
+__export(framework_exports, {
+  ZLINK_PROTOBUF_CONTENT_TYPE: () => ZLINK_PROTOBUF_CONTENT_TYPE,
+  createProtobufEnvelopeMessageSerializer: () => createProtobufEnvelopeMessageSerializer,
+  createProtobufMessageSerializer: () => createProtobufMessageSerializer,
+  createZlinkProtobufEnvelopeCodec: () => createZlinkProtobufEnvelopeCodec,
+  zlinkProtobufCodec: () => zlinkProtobufCodec
+});
+module.exports = __toCommonJS(framework_exports);
+var import_framework = require("@zlink-systems/framework");
+var import_stream_wire2 = require("@zlink-systems/stream-wire");
+
+// packages/framework-codec-protobuf/src/dynamic-value-wire.ts
+function createDynamicValueProtobufType() {
+  return {
+    encode(value) {
+      return { finish: () => encodeDynamicValue(value) };
+    },
+    decode(reader) {
+      return decodeDynamicValue(Buffer.from(reader));
+    }
+  };
+}
+function encodeDynamicValue(value) {
+  if (value === null || value === void 0) {
+    return encodeFields([encodeVarintField(1, 0 /* Null */)]);
+  }
+  if (typeof value === "boolean") {
+    return encodeFields([
+      encodeVarintField(1, 1 /* Bool */),
+      encodeVarintField(2, value ? 1 : 0)
+    ]);
+  }
+  if (typeof value === "number") {
+    return encodeFields([
+      encodeVarintField(1, 2 /* Number */),
+      encodeDoubleField(3, value)
+    ]);
+  }
+  if (typeof value === "string") {
+    return encodeFields([
+      encodeVarintField(1, 3 /* String */),
+      encodeBytesField(4, Buffer.from(value))
+    ]);
+  }
+  if (Array.isArray(value)) {
+    return encodeFields([
+      encodeVarintField(1, 5 /* Array */),
+      ...value.map((item) => encodeBytesField(6, encodeDynamicValue(item)))
+    ]);
+  }
+  if (typeof value === "object") {
+    return encodeFields([
+      encodeVarintField(1, 4 /* Object */),
+      ...Object.entries(value).map(([key, entryValue]) => encodeBytesField(5, encodeObjectEntry(key, entryValue)))
+    ]);
+  }
+  throw new Error(`Protobuf serializer cannot encode value of type '${typeof value}'.`);
+}
+function decodeDynamicValue(bytes) {
+  let kind = 0 /* Null */;
+  let boolValue = false;
+  let numberValue = 0;
+  let stringValue = "";
+  const objectValue = {};
+  const arrayValue = [];
+  for (const field of readFields(bytes)) {
+    switch (field.fieldNumber) {
+      case 1:
+        kind = Number(readVarintPayload(field));
+        break;
+      case 2:
+        boolValue = readVarintPayload(field) !== 0n;
+        break;
+      case 3:
+        numberValue = readDoublePayload(field);
+        break;
+      case 4:
+        stringValue = readBytesPayload(field).toString();
+        break;
+      case 5: {
+        const entry = decodeObjectEntry(readBytesPayload(field));
+        objectValue[entry.key] = entry.value;
+        break;
+      }
+      case 6:
+        arrayValue.push(decodeDynamicValue(readBytesPayload(field)));
+        break;
+      default:
+        break;
+    }
+  }
+  switch (kind) {
+    case 0 /* Null */:
+      return null;
+    case 1 /* Bool */:
+      return boolValue;
+    case 2 /* Number */:
+      return numberValue;
+    case 3 /* String */:
+      return stringValue;
+    case 4 /* Object */:
+      return objectValue;
+    case 5 /* Array */:
+      return arrayValue;
+    default:
+      throw new Error(`Protobuf serializer cannot decode value kind '${kind}'.`);
+  }
+}
+function encodeObjectEntry(key, value) {
+  return encodeFields([
+    encodeBytesField(1, Buffer.from(key)),
+    encodeBytesField(2, encodeDynamicValue(value))
+  ]);
+}
+function decodeObjectEntry(bytes) {
+  let key = "";
+  let value = null;
+  for (const field of readFields(bytes)) {
+    if (field.fieldNumber === 1) {
+      key = readBytesPayload(field).toString();
+    } else if (field.fieldNumber === 2) {
+      value = decodeDynamicValue(readBytesPayload(field));
+    }
+  }
+  return { key, value };
+}
+function encodeFields(fields) {
+  return Buffer.concat(fields);
+}
+function encodeVarintField(fieldNumber, value) {
+  return Buffer.concat([encodeVarint(fieldKey(fieldNumber, 0 /* Varint */)), encodeVarint(value)]);
+}
+function encodeDoubleField(fieldNumber, value) {
+  const payload = Buffer.allocUnsafe(8);
+  payload.writeDoubleLE(value);
+  return Buffer.concat([encodeVarint(fieldKey(fieldNumber, 1 /* Fixed64 */)), payload]);
+}
+function encodeBytesField(fieldNumber, value) {
+  return Buffer.concat([
+    encodeVarint(fieldKey(fieldNumber, 2 /* LengthDelimited */)),
+    encodeVarint(value.length),
+    value
+  ]);
+}
+function fieldKey(fieldNumber, wireType) {
+  return fieldNumber << 3 | wireType;
+}
+function encodeVarint(value) {
+  let remaining = BigInt(value);
+  const bytes = Buffer.allocUnsafe(10);
+  let offset = 0;
+  do {
+    let byte = Number(remaining & 0x7fn);
+    remaining >>= 7n;
+    if (remaining !== 0n) byte |= 128;
+    bytes[offset++] = byte;
+  } while (remaining !== 0n);
+  return Buffer.from(bytes.subarray(0, offset));
+}
+function readFields(bytes) {
+  const fields = [];
+  let offset = 0;
+  while (offset < bytes.length) {
+    const key = readVarint(bytes, offset);
+    offset = key.offset;
+    const fieldNumber = Number(key.value >> 3n);
+    const wireType = Number(key.value & 0x07n);
+    if (wireType === 0 /* Varint */) {
+      const value = readVarint(bytes, offset);
+      fields.push({ fieldNumber, wireType, payload: bytes.subarray(offset, value.offset) });
+      offset = value.offset;
+    } else if (wireType === 1 /* Fixed64 */) {
+      fields.push({ fieldNumber, wireType, payload: bytes.subarray(offset, offset + 8) });
+      offset += 8;
+    } else if (wireType === 2 /* LengthDelimited */) {
+      const length = readVarint(bytes, offset);
+      offset = length.offset;
+      const end = offset + Number(length.value);
+      fields.push({ fieldNumber, wireType, payload: bytes.subarray(offset, end) });
+      offset = end;
+    } else {
+      throw new Error(`Protobuf serializer cannot read wire type '${wireType}'.`);
+    }
+  }
+  return fields;
+}
+function readVarintPayload(field) {
+  ensureWireType(field, 0 /* Varint */);
+  return readVarint(field.payload, 0).value;
+}
+function readDoublePayload(field) {
+  ensureWireType(field, 1 /* Fixed64 */);
+  return field.payload.readDoubleLE();
+}
+function readBytesPayload(field) {
+  ensureWireType(field, 2 /* LengthDelimited */);
+  return field.payload;
+}
+function ensureWireType(field, expected) {
+  if (field.wireType !== expected) {
+    throw new Error(`Protobuf field '${field.fieldNumber}' has wire type '${field.wireType}', not '${expected}'.`);
+  }
+}
+function readVarint(bytes, start) {
+  let value = 0n;
+  let shift = 0n;
+  let offset = start;
+  while (offset < bytes.length) {
+    const byte = BigInt(bytes[offset]);
+    value |= (byte & 0x7fn) << shift;
+    offset += 1;
+    if ((byte & 0x80n) === 0n) return { value, offset };
+    shift += 7n;
+  }
+  throw new Error("Protobuf varint is truncated.");
+}
+
+// packages/framework-codec-protobuf/src/index.ts
+var import_stream_wire = require("@zlink-systems/stream-wire");
+var ZLINK_PROTOBUF_CONTENT_TYPE = "application/x-protobuf";
+function createZlinkStreamProtobufEnvelopeCodec(options) {
+  return {
+    encode(payload, context) {
+      return options.encode(payload, context);
+    },
+    decode(payload) {
+      return options.decode(payload);
+    }
+  };
+}
+
+// packages/framework-codec-protobuf/src/framework.ts
+function zlinkProtobufCodec() {
+  const type = createDynamicValueProtobufType();
+  return {
+    register(codecs) {
+      codecs.addSerializer(ZLINK_PROTOBUF_CONTENT_TYPE, createProtobufMessageSerializer());
+      codecs.addStreamCodec(ZLINK_PROTOBUF_CONTENT_TYPE, this);
+    },
+    encode(payload, messageType) {
+      return {
+        codec: import_stream_wire2.ZlinkStreamCodec.Protobuf,
+        payload: type.encode(payload).finish(),
+        messageType
+      };
+    },
+    decode(payload) {
+      return type.decode(payload.payload);
+    }
+  };
+}
+function createProtobufMessageSerializer() {
+  return {
+    serialize(value) {
+      return import_framework.ZLinkEncodedPayload.from(encodeDynamicValue(value));
+    },
+    deserialize(payload) {
+      const bytes = payload.data();
+      return decodeDynamicValue(
+        Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+      );
+    }
+  };
+}
+function createZlinkProtobufEnvelopeCodec(options) {
+  const streamCodec = createZlinkStreamProtobufEnvelopeCodec(options);
+  return {
+    register(codecs) {
+      codecs.addSerializer(ZLINK_PROTOBUF_CONTENT_TYPE, createProtobufEnvelopeMessageSerializer(options));
+      codecs.addStreamCodec(ZLINK_PROTOBUF_CONTENT_TYPE, this);
+    },
+    encode: streamCodec.encode,
+    decode: streamCodec.decode
+  };
+}
+function createProtobufEnvelopeMessageSerializer(options) {
+  return {
+    serialize(value) {
+      const encoded = options.encode(value, inferMessageType(value));
+      return import_framework.ZLinkEncodedPayload.from(encoded.payload);
+    },
+    deserialize(payload) {
+      return options.decode({
+        codec: import_stream_wire2.ZlinkStreamCodec.Protobuf,
+        payload: payload.data()
+      });
+    }
+  };
+}
+function inferMessageType(value) {
+  if (value === null || value === void 0) return void 0;
+  const constructor = value.constructor;
+  return constructor === Object ? void 0 : constructor;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ZLINK_PROTOBUF_CONTENT_TYPE,
+  createProtobufEnvelopeMessageSerializer,
+  createProtobufMessageSerializer,
+  createZlinkProtobufEnvelopeCodec,
+  zlinkProtobufCodec
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@zlink-systems/framework-codec-protobuf",
+  "version": "0.10.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "files": ["dist/browser", "dist/server", "dist/framework.d.ts", "dist/index.d.ts", "LICENSE"],
+  "exports": {
+    ".": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/browser/index.mjs"
+    },
+    "./framework": {
+      "types": "./dist/framework.d.ts",
+      "require": "./dist/server/framework.cjs",
+      "default": "./dist/server/framework.cjs"
+    }
+  },
+  "dependencies": {
+    "@zlink-systems/stream-wire": "0.10.0"
+  },
+  "peerDependencies": {
+    "@zlink-systems/framework": "0.10.0",
+    "@zlink-systems/stream-connector": "0.10.0"
+  },
+  "peerDependenciesMeta": {
+    "@zlink-systems/framework": { "optional": true }
+  }
+}