@ac-kit/format-osc 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# @ac-kit/format-osc
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [aca1cb1]
+  - @ac-kit/core@0.4.0
+  - @ac-kit/format-core@0.1.4
+
+## 0.1.0
+
+### Minor Changes
+
+- 992cbbb: New package: Open Sound Control 1.0 with the OSC 1.1 additions, from a packet
+  model to the bytes on a UDP or TCP transport.
+  
+  - `OscPacket` models messages and bundles, and `OscArgument` every OSC 1.0 and
+    1.1 type tag under a descriptive name — `int32`, `float32`, `string`, `blob`,
+    `int64`, `timeTag`, `float64`, `symbol`, `char`, `rgba`, `midi`, `true`,
+    `false`, `nil`, `impulse` and nested `array`s.
+  - `encodeOscPacket` writes one packet with every value range-checked, strings
+    as UTF-8 and a type tag string on every message. `decodeOscPacket` reads one
+    as untrusted input: bounds-checked reads, strict NUL padding, unknown type
+    tags refused, bundle and array nesting bounded by `maxDepth` (32 by
+    default), and `OscPacketError` carrying the byte offset on failure. A legacy
+    message with no type tag string decodes with no arguments.
+  - `oscTimeTagFromDate` and `oscTimeTagToDate` convert NTP time tags under the
+    RFC 4330 era rule, covering 1968 to 2104, with `OSC_TIME_TAG_IMMEDIATELY` and
+    `isOscTimeTagImmediately` for the reserved value.
+  - `createOscDatagramCodec` frames one packet per datagram for message-mode
+    transports; `createOscSizePrefixedCodec` frames OSC 1.0 TCP streams with an
+    int32 size prefix and a required `maxPacketSize`, an unusable prefix being a
+    fatal `OscFrameError`. Each pairs a decoder and an encoder also exported on
+    their own.
+
+### Patch Changes
+
+- Updated dependencies [6254a3f]
+  - @ac-kit/format-core@0.1.3

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026 Anthony Champagne and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @ac-kit/format-osc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Open Sound Control 1.0, with the OSC 1.1 additions, in plain data: messages and
+bundles encoded to and decoded from bytes, NTP time tags converted to and from
+dates, and the codecs that frame packets on a datagram or a byte-stream
+transport.
+
+```ts
+import { decodeAll } from "@ac-kit/format-core";
+import {
+  createOscSizePrefixedDecoder,
+  decodeOscPacket,
+  encodeOscPacket,
+  oscTimeTagFromDate,
+} from "@ac-kit/format-osc";
+
+// One UDP datagram.
+const datagram = encodeOscPacket({
+  kind: "bundle",
+  timeTag: oscTimeTagFromDate(Date.now() + 100),
+  elements: [
+    {
+      kind: "message",
+      address: "/oscillator/4/frequency",
+      arguments: [{ type: "float32", value: 440 }],
+    },
+  ],
+});
+decodeOscPacket(datagram);
+
+// Packets read from a TCP stream, OSC 1.0 framing.
+const { items } = decodeAll(
+  createOscSizePrefixedDecoder({ maxPacketSize: 65_536 }),
+  bytes,
+);
+```
+
+It opens no socket: hand the codecs to whatever drives a transport —
+`@ac-kit/format-core`'s `DecodeStream`, or a `FrameLink` from
+`@ac-kit/net-core`.
+
+## Packets
+
+`OscPacket` is an `OscMessage` — an address pattern beginning with `/` and its
+`arguments` — or an `OscBundle` — a `timeTag` and its `elements`, which are
+packets in turn.
+
+`OscArgument` is discriminated by a descriptive `type`, each naming the tag it
+travels under:
+
+| `type`     | tag   | value                                               |
+| ---------- | ----- | --------------------------------------------------- |
+| `int32`    | `i`   | `value`: integer, −2^31 to 2^31 − 1                 |
+| `float32`  | `f`   | `value`: `number`, rounded to binary32              |
+| `string`   | `s`   | `value`: `string`                                   |
+| `blob`     | `b`   | `value`: `Uint8Array`                               |
+| `int64`    | `h`   | `value`: `bigint`, −2^63 to 2^63 − 1                |
+| `timeTag`  | `t`   | `value`: `OscTimeTag`                               |
+| `float64`  | `d`   | `value`: `number`                                   |
+| `symbol`   | `S`   | `value`: `string`                                   |
+| `char`     | `c`   | `value`: one character                              |
+| `rgba`     | `r`   | `red`, `green`, `blue`, `alpha`: 0–255              |
+| `midi`     | `m`   | `port`, `status`, `data1`, `data2`: 0–255           |
+| `true`     | `T`   | —                                                   |
+| `false`    | `F`   | —                                                   |
+| `nil`      | `N`   | —                                                   |
+| `impulse`  | `I`   | — (OSC 1.0's Infinitum)                             |
+| `array`    | `[ ]` | `items`: `OscArgument[]`                            |
+
+`encodeOscPacket` writes one packet. Every message gets a type tag string, `,`
+alone when it has no arguments, and strings are written as UTF-8. A value it
+cannot write as given — an integer out of range, a NUL inside a string, an
+address without its leading `/` — is a `RangeError`, never a silent change.
+
+`decodeOscPacket` reads one packet, and treats its input as untrusted:
+
+- every read is bounds-checked, so a hostile size can make it fail but never
+  read past the input;
+- padding must be NUL bytes, and a packet or bundle element a multiple of 4
+  bytes long;
+- an unknown type tag is an error, because the size of its data is unknowable;
+- strings must be valid UTF-8. OSC 1.0 specifies ASCII, which UTF-8 extends,
+  and UTF-8 is what OSC 1.1 implementations send;
+- bundles and arrays may nest `maxDepth` levels, 32 by default, counted
+  together.
+
+A malformed packet throws `OscPacketError`, a `SyntaxError` carrying the byte
+`offset` it gave up at. A message with no type tag string, which OSC 1.0 asks
+receivers to accept from older senders, decodes with no arguments when nothing
+follows its address; with data after it, the types are unknowable and it is an
+error.
+
+## Time tags
+
+`OscTimeTag` is the 64-bit NTP timestamp of RFC 5905: whole `seconds` since
+1900-01-01T00:00:00Z and a `fraction` of a second in units of 2^-32 s.
+`OSC_TIME_TAG_IMMEDIATELY` is the reserved value asking for dispatch on
+receipt; `isOscTimeTagImmediately` tests for it.
+
+`oscTimeTagFromDate` and `oscTimeTagToDate` convert the others. The `seconds`
+field wraps in 2036, so a tag is read with the RFC 4330 era rule: a value with
+its top bit clear falls after 2036-02-07T06:28:16Z. That names every instant
+from 1968-01-20T03:14:08Z to 2104-02-26T09:42:24Z, and converting a date
+outside that range is a `RangeError`. A whole number of milliseconds survives a
+round trip exactly; a tag converted to a `Date` is rounded to the nearest
+millisecond.
+
+## Framing
+
+A packet carries no length of its own, so each transport frames it:
+
+- **Datagrams** (UDP and other message-mode transports): one packet per
+  datagram. `createOscDatagramCodec` pairs `createOscDatagramDecoder`, which
+  decodes the whole of each datagram, and `createOscDatagramEncoder`. A
+  malformed datagram is a recoverable `error` result, and the next one decodes
+  as usual.
+- **Streams** (TCP), OSC 1.0's framing: each packet preceded by its size as a
+  big-endian int32. `createOscSizePrefixedCodec` pairs
+  `createOscSizePrefixedDecoder` and `createOscSizePrefixedEncoder`. The
+  decoder requires a `maxPacketSize`. A size that is negative, not a multiple
+  of 4 or above that limit is `fatal` with an `OscFrameError`, since nothing
+  else delimits a frame; a malformed packet inside a well-sized frame is a
+  recoverable `error`.
+
+Both are `Decoder`/`Encoder` pairs from `@ac-kit/format-core`, so they run
+under `decodeAll`, `DecodeStream` or a `FrameLink`.
+
+OSC 1.1 frames streams with SLIP (RFC 1055) instead; this package does not read
+that form.
+
+See the
+[generated API docs](https://anthochamp.github.io/node-essentials/api/format-osc/)
+for the full reference.

package/dist/errors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * An OSC packet is malformed: a field is truncated, a string or blob is not
+ * padded with NUL bytes to a multiple of 4, a type tag is unknown, a bundle
+ * element's size does not fit its bundle, nesting exceeds `maxDepth`, or a
+ * string is not valid UTF-8.
+ *
+ * Thrown by {@link decodeOscPacket}, and reported as a recoverable `error`
+ * decode result by the datagram and size-prefixed decoders. A packet built by
+ * the caller that {@link encodeOscPacket} cannot write — an integer out of
+ * range, a NUL inside a string — is a `RangeError` instead.
+ */
+export declare class OscPacketError extends SyntaxError {
+    /** Byte offset in the packet of the field the decoder gave up at. */
+    readonly offset: number;
+    constructor(message: string, 
+    /** Byte offset in the packet of the field the decoder gave up at. */
+    offset: number, options?: ErrorOptions);
+}
+/**
+ * The size prefix of an OSC 1.0 stream frame is unusable: negative, not a
+ * multiple of 4, or above the decoder's `maxPacketSize`.
+ *
+ * Reported as a `fatal` decode result by {@link createOscSizePrefixedDecoder}:
+ * the prefix is the only thing delimiting a frame, so once it cannot be trusted
+ * there is no position to resynchronise from.
+ */
+export declare class OscFrameError extends SyntaxError {
+    /** The declared packet size, as a signed 32-bit integer. */
+    readonly size: number;
+    constructor(message: string, 
+    /** The declared packet size, as a signed 32-bit integer. */
+    size: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAG7C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM;IAHxB,YACC,OAAO,EAAE,MAAM;IACf,qEAAqE;IAC5D,MAAM,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE,YAAY,EAItB;CACD;AAED;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAG5C,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM;IAHtB,YACC,OAAO,EAAE,MAAM;IACf,4DAA4D;IACnD,IAAI,EAAE,MAAM,EAIrB;CACD"}

package/dist/errors.js

@@ -0,0 +1,40 @@
+/**
+ * An OSC packet is malformed: a field is truncated, a string or blob is not
+ * padded with NUL bytes to a multiple of 4, a type tag is unknown, a bundle
+ * element's size does not fit its bundle, nesting exceeds `maxDepth`, or a
+ * string is not valid UTF-8.
+ *
+ * Thrown by {@link decodeOscPacket}, and reported as a recoverable `error`
+ * decode result by the datagram and size-prefixed decoders. A packet built by
+ * the caller that {@link encodeOscPacket} cannot write — an integer out of
+ * range, a NUL inside a string — is a `RangeError` instead.
+ */
+export class OscPacketError extends SyntaxError {
+    offset;
+    constructor(message, 
+    /** Byte offset in the packet of the field the decoder gave up at. */
+    offset, options) {
+        super(`${message} (at byte ${offset})`, options);
+        this.offset = offset;
+        this.name = "OscPacketError";
+    }
+}
+/**
+ * The size prefix of an OSC 1.0 stream frame is unusable: negative, not a
+ * multiple of 4, or above the decoder's `maxPacketSize`.
+ *
+ * Reported as a `fatal` decode result by {@link createOscSizePrefixedDecoder}:
+ * the prefix is the only thing delimiting a frame, so once it cannot be trusted
+ * there is no position to resynchronise from.
+ */
+export class OscFrameError extends SyntaxError {
+    size;
+    constructor(message, 
+    /** The declared packet size, as a signed 32-bit integer. */
+    size) {
+        super(message);
+        this.size = size;
+        this.name = "OscFrameError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,cAAe,SAAQ,WAAW;IAIpC,MAAM;IAHhB,YACC,OAAe;IACf,qEAAqE;IAC5D,MAAc,EACvB,OAAsB;QAEtB,KAAK,CAAC,GAAG,OAAO,aAAa,MAAM,GAAG,EAAE,OAAO,CAAC,CAAC;sBAHxC,MAAM;QAIf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC9B,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IAInC,IAAI;IAHd,YACC,OAAe;IACf,4DAA4D;IACnD,IAAY;QAErB,KAAK,CAAC,OAAO,CAAC,CAAC;oBAFN,IAAI;QAGb,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC7B,CAAC;CACD"}

package/dist/framing/_decode-framed-packet.d.ts

@@ -0,0 +1,9 @@
+import type { DecodeResult } from "@ac-kit/format-core";
+import type { OscPacket } from "../packet/osc-packet.js";
+/**
+ * Decodes `packet` as the whole content of a frame `consumed` units long. A
+ * malformed packet inside an intact frame is a recoverable `error`: the frame
+ * boundary is known, so the next frame is unaffected.
+ */
+export declare function decodeFramedPacket_(packet: Uint8Array, maxDepth: number, consumed: number): DecodeResult<OscPacket>;
+//# sourceMappingURL=_decode-framed-packet.d.ts.map

package/dist/framing/_decode-framed-packet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_decode-framed-packet.d.ts","sourceRoot":"","sources":["../../src/framing/_decode-framed-packet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACd,YAAY,CAAC,SAAS,CAAC,CAazB"}

package/dist/framing/_decode-framed-packet.js

@@ -0,0 +1,23 @@
+import { OscPacketError } from "../errors.js";
+import { readOscPacket_ } from "../packet/_read-osc-packet.js";
+/**
+ * Decodes `packet` as the whole content of a frame `consumed` units long. A
+ * malformed packet inside an intact frame is a recoverable `error`: the frame
+ * boundary is known, so the next frame is unaffected.
+ */
+export function decodeFramedPacket_(packet, maxDepth, consumed) {
+    try {
+        return {
+            status: "decoded",
+            value: readOscPacket_(packet, maxDepth),
+            consumed,
+        };
+    }
+    catch (error) {
+        if (error instanceof OscPacketError) {
+            return { status: "error", error, consumed };
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=_decode-framed-packet.js.map

package/dist/framing/_decode-framed-packet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_decode-framed-packet.js","sourceRoot":"","sources":["../../src/framing/_decode-framed-packet.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAG/D;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAClC,MAAkB,EAClB,QAAgB,EAChB,QAAgB;IAEhB,IAAI,CAAC;QACJ,OAAO;YACN,MAAM,EAAE,SAAS;YACjB,KAAK,EAAE,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC;YACvC,QAAQ;SACR,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;YACrC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;QAC7C,CAAC;QACD,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC"}

package/dist/framing/osc-datagram-codec.d.ts

@@ -0,0 +1,17 @@
+import type { Codec } from "@ac-kit/format-core";
+import type { OscPacket } from "../packet/osc-packet.js";
+import { type OscDatagramDecoderOptions } from "./osc-datagram-decoder.js";
+/** Options for {@link createOscDatagramCodec}. */
+export type OscDatagramCodecOptions = OscDatagramDecoderOptions;
+/**
+ * Creates the OSC codec for a message-mode transport such as UDP: one packet
+ * per datagram, in both directions.
+ *
+ * Use {@link createOscDatagramDecoder} or {@link createOscDatagramEncoder}
+ * directly where only one direction is needed; a `FrameLink` needs both. On a
+ * byte-stream transport use {@link createOscSizePrefixedCodec} instead.
+ *
+ * @throws {RangeError} When `options.maxDepth` is not a non-negative integer.
+ */
+export declare function createOscDatagramCodec(options?: OscDatagramCodecOptions): Codec<OscPacket>;
+//# sourceMappingURL=osc-datagram-codec.d.ts.map

package/dist/framing/osc-datagram-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-datagram-codec.d.ts","sourceRoot":"","sources":["../../src/framing/osc-datagram-codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAEN,KAAK,yBAAyB,EAC9B,MAAM,2BAA2B,CAAC;AAGnC,kDAAkD;AAClD,MAAM,MAAM,uBAAuB,GAAG,yBAAyB,CAAC;AAEhE;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACrC,OAAO,CAAC,EAAE,uBAAuB,GAC/B,KAAK,CAAC,SAAS,CAAC,CAQlB"}

package/dist/framing/osc-datagram-codec.js

@@ -0,0 +1,21 @@
+import { createOscDatagramDecoder, } from "./osc-datagram-decoder.js";
+import { createOscDatagramEncoder } from "./osc-datagram-encoder.js";
+/**
+ * Creates the OSC codec for a message-mode transport such as UDP: one packet
+ * per datagram, in both directions.
+ *
+ * Use {@link createOscDatagramDecoder} or {@link createOscDatagramEncoder}
+ * directly where only one direction is needed; a `FrameLink` needs both. On a
+ * byte-stream transport use {@link createOscSizePrefixedCodec} instead.
+ *
+ * @throws {RangeError} When `options.maxDepth` is not a non-negative integer.
+ */
+export function createOscDatagramCodec(options) {
+    const decoder = createOscDatagramDecoder(options);
+    const encoder = createOscDatagramEncoder();
+    return {
+        decode: (view, context) => decoder.decode(view, context),
+        encode: (value) => encoder.encode(value),
+    };
+}
+//# sourceMappingURL=osc-datagram-codec.js.map

package/dist/framing/osc-datagram-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-datagram-codec.js","sourceRoot":"","sources":["../../src/framing/osc-datagram-codec.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,wBAAwB,GAExB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAKrE;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACrC,OAAiC;IAEjC,MAAM,OAAO,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,wBAAwB,EAAE,CAAC;IAE3C,OAAO;QACN,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC;QACxD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;KACxC,CAAC;AACH,CAAC"}

package/dist/framing/osc-datagram-decoder.d.ts

@@ -0,0 +1,22 @@
+import type { Decoder } from "@ac-kit/format-core";
+import type { DecodeOscPacketOptions } from "../packet/decode-osc-packet.js";
+import type { OscPacket } from "../packet/osc-packet.js";
+/** Options for {@link createOscDatagramDecoder}. */
+export type OscDatagramDecoderOptions = DecodeOscPacketOptions;
+/**
+ * Creates the read half for a message-mode transport such as UDP, where every
+ * delivery is exactly one OSC packet.
+ *
+ * Each call decodes the whole view as one packet and consumes all of it. A
+ * malformed datagram is a recoverable `error` carrying an
+ * {@link OscPacketError}: it is dropped and the next datagram decodes as usual.
+ * The decoder never answers `incomplete` — a datagram cannot grow — so it is
+ * only meaningful where the driver hands it one datagram per call; on a byte
+ * stream use {@link createOscSizePrefixedDecoder}.
+ *
+ * Time is O(n) in the datagram's length.
+ *
+ * @throws {RangeError} When `options.maxDepth` is not a non-negative integer.
+ */
+export declare function createOscDatagramDecoder(options?: OscDatagramDecoderOptions): Decoder<OscPacket>;
+//# sourceMappingURL=osc-datagram-decoder.d.ts.map

package/dist/framing/osc-datagram-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-datagram-decoder.d.ts","sourceRoot":"","sources":["../../src/framing/osc-datagram-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,qBAAqB,CAAC;AAGjE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGzD,oDAAoD;AACpD,MAAM,MAAM,yBAAyB,GAAG,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,CAAC,EAAE,yBAAyB,GACjC,OAAO,CAAC,SAAS,CAAC,CAQpB"}

package/dist/framing/osc-datagram-decoder.js

@@ -0,0 +1,26 @@
+import { resolveMaxDepth_ } from "../packet/_read-osc-packet.js";
+import { decodeFramedPacket_ } from "./_decode-framed-packet.js";
+/**
+ * Creates the read half for a message-mode transport such as UDP, where every
+ * delivery is exactly one OSC packet.
+ *
+ * Each call decodes the whole view as one packet and consumes all of it. A
+ * malformed datagram is a recoverable `error` carrying an
+ * {@link OscPacketError}: it is dropped and the next datagram decodes as usual.
+ * The decoder never answers `incomplete` — a datagram cannot grow — so it is
+ * only meaningful where the driver hands it one datagram per call; on a byte
+ * stream use {@link createOscSizePrefixedDecoder}.
+ *
+ * Time is O(n) in the datagram's length.
+ *
+ * @throws {RangeError} When `options.maxDepth` is not a non-negative integer.
+ */
+export function createOscDatagramDecoder(options) {
+    const maxDepth = resolveMaxDepth_(options?.maxDepth);
+    return {
+        decode(view) {
+            return decodeFramedPacket_(view, maxDepth, view.length);
+        },
+    };
+}
+//# sourceMappingURL=osc-datagram-decoder.js.map

package/dist/framing/osc-datagram-decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-datagram-decoder.js","sourceRoot":"","sources":["../../src/framing/osc-datagram-decoder.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAKjE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CACvC,OAAmC;IAEnC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAErD,OAAO;QACN,MAAM,CAAC,IAAgB;YACtB,OAAO,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACzD,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/framing/osc-datagram-encoder.d.ts

@@ -0,0 +1,8 @@
+import type { Encoder } from "@ac-kit/format-core";
+import type { OscPacket } from "../packet/osc-packet.js";
+/**
+ * Creates the write half for a message-mode transport such as UDP: each packet
+ * becomes one datagram, exactly as {@link encodeOscPacket} writes it.
+ */
+export declare function createOscDatagramEncoder(): Encoder<OscPacket>;
+//# sourceMappingURL=osc-datagram-encoder.d.ts.map

package/dist/framing/osc-datagram-encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-datagram-encoder.d.ts","sourceRoot":"","sources":["../../src/framing/osc-datagram-encoder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAAC,SAAS,CAAC,CAE7D"}

package/dist/framing/osc-datagram-encoder.js

@@ -0,0 +1,9 @@
+import { encodeOscPacket } from "../packet/encode-osc-packet.js";
+/**
+ * Creates the write half for a message-mode transport such as UDP: each packet
+ * becomes one datagram, exactly as {@link encodeOscPacket} writes it.
+ */
+export function createOscDatagramEncoder() {
+    return { encode: encodeOscPacket };
+}
+//# sourceMappingURL=osc-datagram-encoder.js.map

package/dist/framing/osc-datagram-encoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-datagram-encoder.js","sourceRoot":"","sources":["../../src/framing/osc-datagram-encoder.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjE;;;GAGG;AACH,MAAM,UAAU,wBAAwB;IACvC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;AACpC,CAAC"}

package/dist/framing/osc-size-prefixed-codec.d.ts

@@ -0,0 +1,19 @@
+import type { Codec } from "@ac-kit/format-core";
+import type { OscPacket } from "../packet/osc-packet.js";
+import { type OscSizePrefixedDecoderOptions } from "./osc-size-prefixed-decoder.js";
+/** Options for {@link createOscSizePrefixedCodec}. */
+export type OscSizePrefixedCodecOptions = OscSizePrefixedDecoderOptions;
+/**
+ * Creates the OSC codec for a byte-stream transport such as TCP, using OSC
+ * 1.0's stream framing: each packet preceded by its size as a big-endian
+ * int32.
+ *
+ * Use {@link createOscSizePrefixedDecoder} or
+ * {@link createOscSizePrefixedEncoder} directly where only one direction is
+ * needed; a `FrameLink` needs both. On a message-mode transport use
+ * {@link createOscDatagramCodec} instead.
+ *
+ * @throws {RangeError} As {@link createOscSizePrefixedDecoder}.
+ */
+export declare function createOscSizePrefixedCodec(options: OscSizePrefixedCodecOptions): Codec<OscPacket>;
+//# sourceMappingURL=osc-size-prefixed-codec.d.ts.map

package/dist/framing/osc-size-prefixed-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-size-prefixed-codec.d.ts","sourceRoot":"","sources":["../../src/framing/osc-size-prefixed-codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAEN,KAAK,6BAA6B,EAClC,MAAM,gCAAgC,CAAC;AAGxC,sDAAsD;AACtD,MAAM,MAAM,2BAA2B,GAAG,6BAA6B,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,2BAA2B,GAClC,KAAK,CAAC,SAAS,CAAC,CAQlB"}

package/dist/framing/osc-size-prefixed-codec.js

@@ -0,0 +1,23 @@
+import { createOscSizePrefixedDecoder, } from "./osc-size-prefixed-decoder.js";
+import { createOscSizePrefixedEncoder } from "./osc-size-prefixed-encoder.js";
+/**
+ * Creates the OSC codec for a byte-stream transport such as TCP, using OSC
+ * 1.0's stream framing: each packet preceded by its size as a big-endian
+ * int32.
+ *
+ * Use {@link createOscSizePrefixedDecoder} or
+ * {@link createOscSizePrefixedEncoder} directly where only one direction is
+ * needed; a `FrameLink` needs both. On a message-mode transport use
+ * {@link createOscDatagramCodec} instead.
+ *
+ * @throws {RangeError} As {@link createOscSizePrefixedDecoder}.
+ */
+export function createOscSizePrefixedCodec(options) {
+    const decoder = createOscSizePrefixedDecoder(options);
+    const encoder = createOscSizePrefixedEncoder();
+    return {
+        decode: (view, context) => decoder.decode(view, context),
+        encode: (value) => encoder.encode(value),
+    };
+}
+//# sourceMappingURL=osc-size-prefixed-codec.js.map

package/dist/framing/osc-size-prefixed-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-size-prefixed-codec.js","sourceRoot":"","sources":["../../src/framing/osc-size-prefixed-codec.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,4BAA4B,GAE5B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAK9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CACzC,OAAoC;IAEpC,MAAM,OAAO,GAAG,4BAA4B,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,4BAA4B,EAAE,CAAC;IAE/C,OAAO;QACN,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC;QACxD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;KACxC,CAAC;AACH,CAAC"}

package/dist/framing/osc-size-prefixed-decoder.d.ts

@@ -0,0 +1,40 @@
+import { type Decoder } from "@ac-kit/format-core";
+import type { DecodeOscPacketOptions } from "../packet/decode-osc-packet.js";
+import type { OscPacket } from "../packet/osc-packet.js";
+/** Options for {@link createOscSizePrefixedDecoder}. */
+export type OscSizePrefixedDecoderOptions = DecodeOscPacketOptions & {
+    /**
+     * Largest packet size, in bytes, a frame may declare. Required: the prefix
+     * can announce up to 2 GiB, and only the caller knows what its peers send. A
+     * frame is held in the driver's buffer until it is complete, so this also
+     * bounds what one frame can make that buffer retain.
+     */
+    maxPacketSize: number;
+};
+/**
+ * Creates the read half of OSC 1.0's stream framing, for a byte-stream
+ * transport such as TCP: each packet preceded by its size as a big-endian
+ * int32.
+ *
+ * - Until the 4-byte prefix and then the whole packet have arrived, the result is
+ *   `incomplete` with `needAtLeast` set to the bytes required.
+ * - A declared size that is negative, not a multiple of 4, or above
+ *   `maxPacketSize` is `fatal` with an {@link OscFrameError}: the prefix is the
+ *   only frame delimiter, so once it is wrong there is nothing to resynchronise
+ *   on. It is rejected as soon as the prefix arrives, before any of the packet
+ *   is buffered.
+ * - A malformed packet inside a well-sized frame is a recoverable `error`
+ *   carrying an {@link OscPacketError}, whose `offset` counts from the start of
+ *   the packet, after the prefix. The frame is consumed and the next one
+ *   decodes as usual.
+ *
+ * OSC 1.1 frames streams with SLIP instead; this decoder reads the OSC 1.0
+ * form, which most TCP implementations still send.
+ *
+ * Time is O(n) in the frame's size per decoded frame.
+ *
+ * @throws {RangeError} When `maxPacketSize` is not a non-negative integer, or
+ *   `maxDepth` as {@link decodeOscPacket}.
+ */
+export declare function createOscSizePrefixedDecoder(options: OscSizePrefixedDecoderOptions): Decoder<OscPacket>;
+//# sourceMappingURL=osc-size-prefixed-decoder.d.ts.map

package/dist/framing/osc-size-prefixed-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-size-prefixed-decoder.d.ts","sourceRoot":"","sources":["../../src/framing/osc-size-prefixed-decoder.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,OAAO,EAEZ,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGzD,wDAAwD;AACxD,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACpE;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,6BAA6B,GACpC,OAAO,CAAC,SAAS,CAAC,CAoCpB"}

package/dist/framing/osc-size-prefixed-decoder.js

@@ -0,0 +1,59 @@
+import { getUint32Be } from "@ac-kit/core";
+import { decodeIncomplete, } from "@ac-kit/format-core";
+import { OscFrameError } from "../errors.js";
+import { resolveMaxDepth_ } from "../packet/_read-osc-packet.js";
+import { decodeFramedPacket_ } from "./_decode-framed-packet.js";
+/**
+ * Creates the read half of OSC 1.0's stream framing, for a byte-stream
+ * transport such as TCP: each packet preceded by its size as a big-endian
+ * int32.
+ *
+ * - Until the 4-byte prefix and then the whole packet have arrived, the result is
+ *   `incomplete` with `needAtLeast` set to the bytes required.
+ * - A declared size that is negative, not a multiple of 4, or above
+ *   `maxPacketSize` is `fatal` with an {@link OscFrameError}: the prefix is the
+ *   only frame delimiter, so once it is wrong there is nothing to resynchronise
+ *   on. It is rejected as soon as the prefix arrives, before any of the packet
+ *   is buffered.
+ * - A malformed packet inside a well-sized frame is a recoverable `error`
+ *   carrying an {@link OscPacketError}, whose `offset` counts from the start of
+ *   the packet, after the prefix. The frame is consumed and the next one
+ *   decodes as usual.
+ *
+ * OSC 1.1 frames streams with SLIP instead; this decoder reads the OSC 1.0
+ * form, which most TCP implementations still send.
+ *
+ * Time is O(n) in the frame's size per decoded frame.
+ *
+ * @throws {RangeError} When `maxPacketSize` is not a non-negative integer, or
+ *   `maxDepth` as {@link decodeOscPacket}.
+ */
+export function createOscSizePrefixedDecoder(options) {
+    const { maxPacketSize } = options;
+    if (!Number.isInteger(maxPacketSize) || maxPacketSize < 0) {
+        throw new RangeError(`maxPacketSize must be a non-negative integer, got ${maxPacketSize}`);
+    }
+    const maxDepth = resolveMaxDepth_(options.maxDepth);
+    return {
+        decode(view) {
+            if (view.length < 4) {
+                return decodeIncomplete(4);
+            }
+            const size = getUint32Be(view, 0) | 0;
+            if (size < 0 || size % 4 !== 0 || size > maxPacketSize) {
+                return {
+                    status: "fatal",
+                    error: new OscFrameError(size > maxPacketSize
+                        ? `OSC frame size ${size} exceeds the ${maxPacketSize} byte limit`
+                        : `OSC frame size ${size} is not a non-negative multiple of 4`, size),
+                };
+            }
+            const total = 4 + size;
+            if (view.length < total) {
+                return decodeIncomplete(total);
+            }
+            return decodeFramedPacket_(view.subarray(4, total), maxDepth, total);
+        },
+    };
+}
+//# sourceMappingURL=osc-size-prefixed-decoder.js.map

package/dist/framing/osc-size-prefixed-decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"osc-size-prefixed-decoder.js","sourceRoot":"","sources":["../../src/framing/osc-size-prefixed-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EACN,gBAAgB,GAGhB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAajE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,4BAA4B,CAC3C,OAAsC;IAEtC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAClC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,UAAU,CACnB,qDAAqD,aAAa,EAAE,CACpE,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEpD,OAAO;QACN,MAAM,CAAC,IAAgB;YACtB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC;YAC5B,CAAC;YAED,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;YACtC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,aAAa,EAAE,CAAC;gBACxD,OAAO;oBACN,MAAM,EAAE,OAAO;oBACf,KAAK,EAAE,IAAI,aAAa,CACvB,IAAI,GAAG,aAAa;wBACnB,CAAC,CAAC,kBAAkB,IAAI,gBAAgB,aAAa,aAAa;wBAClE,CAAC,CAAC,kBAAkB,IAAI,sCAAsC,EAC/D,IAAI,CACJ;iBACD,CAAC;YACH,CAAC;YAED,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC;YACvB,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;gBACzB,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;YAChC,CAAC;YAED,OAAO,mBAAmB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QACtE,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/framing/osc-size-prefixed-encoder.d.ts

@@ -0,0 +1,10 @@
+import type { Encoder } from "@ac-kit/format-core";
+import type { OscPacket } from "../packet/osc-packet.js";
+/**
+ * Creates the write half of OSC 1.0's stream framing: each packet preceded by
+ * its size as a big-endian int32, in one buffer.
+ *
+ * @throws {RangeError} From `encode`, as {@link encodeOscPacket}.
+ */
+export declare function createOscSizePrefixedEncoder(): Encoder<OscPacket>;
+//# sourceMappingURL=osc-size-prefixed-encoder.d.ts.map