@flighthq/buffer 0.0.0-stage → 0.5.1-next.3302.76ece6b

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright (c) 2013-2026 Joshua Granick and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @flighthq/buffer
 
-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.
+Byte-level buffer reading utilities
+
+## Install
+
+```sh
+npm install @flighthq/buffer
+```
+
+Import the supported application-facing API from `@flighthq/buffer`. The `@flighthq/buffer/contract` export is the wider package-to-package contract used to compose Flight itself.
+
+This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
+
+- [Flight project](https://github.com/flighthq/flight)
+- [Source for @flighthq/buffer@0.5.1-next.3302.76ece6b](https://github.com/flighthq/flight/tree/76ece6bee38e3d07816f341b7f017bfcec3e8e29/packages/buffer)
+- [License](https://github.com/flighthq/flight/blob/76ece6bee38e3d07816f341b7f017bfcec3e8e29/LICENSE.md)

package/dist/byteReader.d.ts

@@ -0,0 +1,13 @@
+export type { ByteReader } from '@flighthq/types/contract';
+import type { ByteReader, NonEntityCreateResult } from '@flighthq/types/contract';
+export declare function createByteReader(bytes: Readonly<Uint8Array>, offset?: number): NonEntityCreateResult<ByteReader, 'descriptor'>;
+export declare function hasByteReaderBytes(reader: Readonly<ByteReader>, count: number): boolean;
+export declare function readByteReaderU16(reader: ByteReader): number;
+export declare function readByteReaderU24(reader: ByteReader): number;
+export declare function readByteReaderU24BigEndian(reader: ByteReader): number;
+export declare function readByteReaderU32(reader: ByteReader): number;
+export declare function readByteReaderU32BigEndian(reader: ByteReader): number;
+export declare function readByteReaderU64(reader: ByteReader): number;
+export declare function readByteReaderU8(reader: ByteReader): number;
+export declare function skipByteReader(reader: ByteReader, count: number): void;
+//# sourceMappingURL=byteReader.d.ts.map

package/dist/byteReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byteReader.d.ts","sourceRoot":"","sources":["../src/byteReader.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAElF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,EAC3B,MAAM,SAAI,GACT,qBAAqB,CAAC,UAAU,EAAE,YAAY,CAAC,CAEjD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAI5D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAM5D;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAMrE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAI5D;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAIrE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAK5D;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAI3D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEtE"}

package/dist/byteReader.js

@@ -0,0 +1,50 @@
+export function createByteReader(bytes, offset = 0) {
+    return { view: new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength), offset };
+}
+export function hasByteReaderBytes(reader, count) {
+    return count >= 0 && reader.offset + count <= reader.view.byteLength;
+}
+export function readByteReaderU16(reader) {
+    const value = reader.view.getUint16(reader.offset, true);
+    reader.offset += 2;
+    return value;
+}
+export function readByteReaderU24(reader) {
+    const view = reader.view;
+    const offset = reader.offset;
+    const value = view.getUint8(offset) | (view.getUint8(offset + 1) << 8) | (view.getUint8(offset + 2) << 16);
+    reader.offset += 3;
+    return value;
+}
+export function readByteReaderU24BigEndian(reader) {
+    const view = reader.view;
+    const offset = reader.offset;
+    const value = (view.getUint8(offset) << 16) | (view.getUint8(offset + 1) << 8) | view.getUint8(offset + 2);
+    reader.offset += 3;
+    return value;
+}
+export function readByteReaderU32(reader) {
+    const value = reader.view.getUint32(reader.offset, true);
+    reader.offset += 4;
+    return value;
+}
+export function readByteReaderU32BigEndian(reader) {
+    const value = reader.view.getUint32(reader.offset, false);
+    reader.offset += 4;
+    return value;
+}
+export function readByteReaderU64(reader) {
+    const low = reader.view.getUint32(reader.offset, true);
+    const high = reader.view.getUint32(reader.offset + 4, true);
+    reader.offset += 8;
+    return high * 0x1_0000_0000 + low;
+}
+export function readByteReaderU8(reader) {
+    const value = reader.view.getUint8(reader.offset);
+    reader.offset += 1;
+    return value;
+}
+export function skipByteReader(reader, count) {
+    reader.offset += count;
+}
+//# sourceMappingURL=byteReader.js.map

package/dist/byteReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"byteReader.js","sourceRoot":"","sources":["../src/byteReader.ts"],"names":[],"mappings":"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"}

package/dist/contract.d.ts

@@ -0,0 +1,2 @@
+export * from './byteReader.ts';
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/contract.js

@@ -0,0 +1,2 @@
+export * from "./byteReader.js";
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './byteReader.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./byteReader.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@flighthq/buffer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.1-next.3302.76ece6b",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/buffer"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.5.1-next.3302.76ece6b"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Byte-level buffer reading utilities",
+  "sideEffects": false
+}

package/src/byteReader.test.ts

@@ -0,0 +1,117 @@
+import {
+  createByteReader,
+  hasByteReaderBytes,
+  readByteReaderU16,
+  readByteReaderU24,
+  readByteReaderU24BigEndian,
+  readByteReaderU32,
+  readByteReaderU32BigEndian,
+  readByteReaderU64,
+  readByteReaderU8,
+  skipByteReader,
+} from './byteReader.ts';
+
+describe('createByteReader', () => {
+  it('starts at the given offset', () => {
+    const reader = createByteReader(new Uint8Array([1, 2, 3, 4]), 2);
+    expect(reader.offset).toBe(2);
+    expect(readByteReaderU8(reader)).toBe(3);
+  });
+
+  it('views a subarray by its byteOffset', () => {
+    const backing = new Uint8Array([9, 9, 0x01, 0x00]);
+    const reader = createByteReader(backing.subarray(2));
+    expect(readByteReaderU16(reader)).toBe(1);
+  });
+});
+
+describe('hasByteReaderBytes', () => {
+  it('reports whether count bytes remain from the current offset', () => {
+    const reader = createByteReader(new Uint8Array(8), 4);
+    expect(hasByteReaderBytes(reader, 4)).toBe(true);
+    expect(hasByteReaderBytes(reader, 5)).toBe(false);
+    expect(hasByteReaderBytes(reader, 0)).toBe(true);
+  });
+});
+
+describe('readByteReaderU16', () => {
+  it('reads little-endian and advances 2', () => {
+    const reader = createByteReader(new Uint8Array([0x34, 0x12]));
+    expect(readByteReaderU16(reader)).toBe(0x1234);
+    expect(reader.offset).toBe(2);
+  });
+});
+
+describe('readByteReaderU24', () => {
+  it('reads a 3-byte little-endian value and advances 3', () => {
+    const reader = createByteReader(new Uint8Array([0x56, 0x34, 0x12]));
+    expect(readByteReaderU24(reader)).toBe(0x123456);
+    expect(reader.offset).toBe(3);
+  });
+
+  it('reads the full 24-bit range without sign issues', () => {
+    const reader = createByteReader(new Uint8Array([0xff, 0xff, 0xff]));
+    expect(readByteReaderU24(reader)).toBe(0xffffff);
+  });
+});
+
+describe('readByteReaderU24BigEndian', () => {
+  it('reads a 3-byte big-endian value and advances 3', () => {
+    const reader = createByteReader(new Uint8Array([0x12, 0x34, 0x56]));
+    expect(readByteReaderU24BigEndian(reader)).toBe(0x123456);
+    expect(reader.offset).toBe(3);
+  });
+
+  it('reads the full 24-bit range without sign issues', () => {
+    const reader = createByteReader(new Uint8Array([0xff, 0xff, 0xff]));
+    expect(readByteReaderU24BigEndian(reader)).toBe(0xffffff);
+  });
+});
+
+describe('readByteReaderU32', () => {
+  it('reads little-endian and advances 4', () => {
+    const reader = createByteReader(new Uint8Array([0x78, 0x56, 0x34, 0x12]));
+    expect(readByteReaderU32(reader)).toBe(0x12345678);
+    expect(reader.offset).toBe(4);
+  });
+});
+
+describe('readByteReaderU32BigEndian', () => {
+  it('reads a 4-byte big-endian value and advances 4', () => {
+    const reader = createByteReader(new Uint8Array([0x12, 0x34, 0x56, 0x78]));
+    expect(readByteReaderU32BigEndian(reader)).toBe(0x12345678);
+    expect(reader.offset).toBe(4);
+  });
+
+  it('reads the full 32-bit range as an unsigned value', () => {
+    const reader = createByteReader(new Uint8Array([0xff, 0xff, 0xff, 0xff]));
+    expect(readByteReaderU32BigEndian(reader)).toBe(0xffffffff);
+  });
+});
+
+describe('readByteReaderU64', () => {
+  it('reads little-endian as a number and advances 8', () => {
+    const bytes = new Uint8Array(8);
+    new DataView(bytes.buffer).setUint32(0, 0x1000, true);
+    new DataView(bytes.buffer).setUint32(4, 0x2, true);
+    const reader = createByteReader(bytes);
+    expect(readByteReaderU64(reader)).toBe(0x2 * 0x1_0000_0000 + 0x1000);
+    expect(reader.offset).toBe(8);
+  });
+});
+
+describe('readByteReaderU8', () => {
+  it('reads one byte and advances 1', () => {
+    const reader = createByteReader(new Uint8Array([0xab]));
+    expect(readByteReaderU8(reader)).toBe(0xab);
+    expect(reader.offset).toBe(1);
+  });
+});
+
+describe('skipByteReader', () => {
+  it('advances the offset without reading', () => {
+    const reader = createByteReader(new Uint8Array(8));
+    skipByteReader(reader, 3);
+    expect(reader.offset).toBe(3);
+  });
+});