Initial Commit

packages/foundation/flow/streams/src/utils/buffer/uint8-slice/uint8-slice.md

@@ -0,0 +1,68 @@
+# createUint8ArraySlice
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`createUint8ArraySlice` returns an independent copy of a sub-range of a
+`Uint8Array`. The streams package favours explicit copy-vs-view semantics over
+the conventional `subarray` (view) / `slice` (copy) ambiguity that has bitten
+many consumers writing both browser and Node code. This helper makes the
+intent obvious at the call site: when you call `createUint8ArraySlice`, you
+get back memory you fully own.
+
+It is functionally a thin wrapper around `Uint8Array.prototype.slice`, but
+named to communicate the copy semantics, and centralised so that future
+optimisations (e.g. fast-path detection of zero-length, large-buffer pooling)
+have a single place to live.
+
+## Features
+
+- Always copies — never returns a view aliasing the source buffer.
+- Clamps `end` past `length` per the standard `slice` algorithm.
+- Returns an empty `Uint8Array` when `start === end`.
+- Pure, synchronous, dependency-free.
+
+## Usage: Basic Example
+
+```ts
+import { createUint8ArraySlice } from "@suaveplan/streams/utils/buffer/uint8-slice/uint8-slice";
+
+const src = new Uint8Array([1, 2, 3, 4, 5]);
+const middle = createUint8ArraySlice(src, 1, 4); // Uint8Array(3) [2, 3, 4]
+```
+
+## Usage: Advanced Example
+
+```ts
+import { createUint8ArraySlice } from "@suaveplan/streams/utils/buffer/uint8-slice/uint8-slice";
+
+// Frame parser: each frame owns its bytes so the surrounding ring buffer can
+// be recycled without stalling downstream consumers.
+function parseFrames(buf: Uint8Array, frameSize: number): Uint8Array[] {
+    const out: Uint8Array[] = [];
+    for (let i = 0; i + frameSize <= buf.byteLength; i += frameSize) {
+        out.push(createUint8ArraySlice(buf, i, i + frameSize));
+    }
+    return out;
+}
+```
+
+## API Reference
+
+### `createUint8ArraySlice(array, start, end): Uint8Array`
+
+- **`array: Uint8Array`** — source buffer.
+- **`start: number`** — inclusive start index.
+- **`end: number`** — exclusive end index; clamped to `array.length`.
+- **Returns** — a fresh `Uint8Array` of length `max(0, end - start)`.
+- **Throws** — never.
+
+## Implementation Notes
+
+- Implemented as `array.slice(start, end)`. The function exists because the
+  copy-vs-view distinction matters for streams correctness (subarray would
+  hold the entire upstream buffer alive) and a named helper documents intent
+  better than an inline `.slice` call would.
+- Universal: zero environment dependencies.