tessl/npm-ow

Function argument validation for humans with expressive, chainable API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Typed Array Validation

Name: tessl/npm-ow
Author: tessl

Comprehensive validation for all typed array types including length constraints, byte length validation, and binary data validation methods.

Capabilities

Generic Typed Array Validation

Base validation for any typed array with common length and byte length methods.

/** Generic typed array validation predicate */
interface TypedArrayPredicate<T extends TypedArray> extends BasePredicate<T> {
  // Length validation (number of elements)
  length(length: number): TypedArrayPredicate<T>;
  minLength(length: number): TypedArrayPredicate<T>;
  maxLength(length: number): TypedArrayPredicate<T>;
  
  // Byte length validation (total bytes)
  byteLength(byteLength: number): TypedArrayPredicate<T>;
  minByteLength(byteLength: number): TypedArrayPredicate<T>;
  maxByteLength(byteLength: number): TypedArrayPredicate<T>;
}

/** Base typed array type */
type TypedArray = 
  | Int8Array 
  | Uint8Array 
  | Uint8ClampedArray 
  | Int16Array 
  | Uint16Array 
  | Int32Array 
  | Uint32Array 
  | Float32Array 
  | Float64Array;

8-bit Typed Arrays

Validation for 8-bit typed arrays with 1 byte per element.

/** 8-bit signed integer array (-128 to 127) */
const int8Array: TypedArrayPredicate<Int8Array>;

/** 8-bit unsigned integer array (0 to 255) */
const uint8Array: TypedArrayPredicate<Uint8Array>;

/** 8-bit unsigned integer clamped array (0 to 255, clamped) */
const uint8ClampedArray: TypedArrayPredicate<Uint8ClampedArray>;

Usage Examples:

import ow from 'ow';

// Int8Array validation
const int8 = new Int8Array([127, -128, 0]);
ow(int8, ow.int8Array);
ow(int8, ow.int8Array.length(3));
ow(int8, ow.int8Array.byteLength(3)); // 3 elements × 1 byte = 3 bytes

// Uint8Array validation
const uint8 = new Uint8Array([255, 0, 128]);
ow(uint8, ow.uint8Array);
ow(uint8, ow.uint8Array.minLength(2));
ow(uint8, ow.uint8Array.maxByteLength(10));

// Uint8ClampedArray validation (used in Canvas ImageData)
const clamped = new Uint8ClampedArray([300, -50, 128]); // Values clamped to 0-255
ow(clamped, ow.uint8ClampedArray);
ow(clamped, ow.uint8ClampedArray.length(3));

16-bit Typed Arrays

Validation for 16-bit typed arrays with 2 bytes per element.

/** 16-bit signed integer array (-32768 to 32767) */
const int16Array: TypedArrayPredicate<Int16Array>;

/** 16-bit unsigned integer array (0 to 65535) */
const uint16Array: TypedArrayPredicate<Uint16Array>;

Usage Examples:

import ow from 'ow';

// Int16Array validation
const int16 = new Int16Array([32767, -32768, 0]);
ow(int16, ow.int16Array);
ow(int16, ow.int16Array.length(3));
ow(int16, ow.int16Array.byteLength(6)); // 3 elements × 2 bytes = 6 bytes

// Uint16Array validation
const uint16 = new Uint16Array([65535, 0, 32768]);
ow(uint16, ow.uint16Array);
ow(uint16, ow.uint16Array.minLength(2));
ow(uint16, ow.uint16Array.maxByteLength(20));

32-bit Typed Arrays

Validation for 32-bit typed arrays with 4 bytes per element.

/** 32-bit signed integer array (-2147483648 to 2147483647) */
const int32Array: TypedArrayPredicate<Int32Array>;

/** 32-bit unsigned integer array (0 to 4294967295) */
const uint32Array: TypedArrayPredicate<Uint32Array>;

/** 32-bit floating point array */
const float32Array: TypedArrayPredicate<Float32Array>;

Usage Examples:

import ow from 'ow';

// Int32Array validation
const int32 = new Int32Array([2147483647, -2147483648, 0]);
ow(int32, ow.int32Array);
ow(int32, ow.int32Array.length(3));
ow(int32, ow.int32Array.byteLength(12)); // 3 elements × 4 bytes = 12 bytes

// Uint32Array validation
const uint32 = new Uint32Array([4294967295, 0, 2147483648]);
ow(uint32, ow.uint32Array);
ow(uint32, ow.uint32Array.minLength(1));

// Float32Array validation
const float32 = new Float32Array([3.14159, -2.71828, 0.0]);
ow(float32, ow.float32Array);
ow(float32, ow.float32Array.maxLength(10));
ow(float32, ow.float32Array.byteLength(12)); // 3 elements × 4 bytes = 12 bytes

64-bit Typed Arrays

Validation for 64-bit floating point arrays with 8 bytes per element.

/** 64-bit floating point array */
const float64Array: TypedArrayPredicate<Float64Array>;

Usage Examples:

import ow from 'ow';

// Float64Array validation
const float64 = new Float64Array([Math.PI, Math.E, Number.MAX_VALUE]);
ow(float64, ow.float64Array);
ow(float64, ow.float64Array.length(3));
ow(float64, ow.float64Array.byteLength(24)); // 3 elements × 8 bytes = 24 bytes

// High precision validation
ow(float64, ow.float64Array.minByteLength(8));
ow(float64, ow.float64Array.maxByteLength(1024));

Generic Typed Array Validation

Validation for any typed array when the specific type is not known.

/** Generic typed array validation */
const typedArray: TypedArrayPredicate<TypedArray>;

Usage Examples:

import ow from 'ow';

// Generic typed array validation
ow(new Int8Array([1, 2, 3]), ow.typedArray);
ow(new Float32Array([1.1, 2.2, 3.3]), ow.typedArray);
ow(new Uint16Array([100, 200, 300]), ow.typedArray);

// When you don't know the specific type
function processTypedArray(data: unknown) {
  ow(data, ow.typedArray.minLength(1));
  
  const typedData = data as TypedArray;
  console.log(`Array type: ${typedData.constructor.name}`);
  console.log(`Length: ${typedData.length}`);
  console.log(`Byte length: ${typedData.byteLength}`);
}

ArrayBuffer and DataView Validation

ArrayBuffer Validation

Validation for ArrayBuffer objects with byte length constraints.

/** ArrayBuffer validation predicate */
interface ArrayBufferPredicate<T extends ArrayBuffer> extends BasePredicate<T> {
  byteLength(byteLength: number): ArrayBufferPredicate<T>;
  minByteLength(byteLength: number): ArrayBufferPredicate<T>;
  maxByteLength(byteLength: number): ArrayBufferPredicate<T>;
}

/** Standard ArrayBuffer validation */
const arrayBuffer: ArrayBufferPredicate<ArrayBuffer>;

/** SharedArrayBuffer validation */
const sharedArrayBuffer: ArrayBufferPredicate<SharedArrayBuffer>;

Usage Examples:

import ow from 'ow';

// ArrayBuffer validation
const buffer = new ArrayBuffer(16);
ow(buffer, ow.arrayBuffer);
ow(buffer, ow.arrayBuffer.byteLength(16));
ow(buffer, ow.arrayBuffer.minByteLength(8));
ow(buffer, ow.arrayBuffer.maxByteLength(32));

// SharedArrayBuffer validation (if supported)
if (typeof SharedArrayBuffer !== 'undefined') {
  const sharedBuffer = new SharedArrayBuffer(32);
  ow(sharedBuffer, ow.sharedArrayBuffer);
  ow(sharedBuffer, ow.sharedArrayBuffer.byteLength(32));
}

DataView Validation

Validation for DataView objects with byte length constraints.

/** DataView validation predicate */
interface DataViewPredicate extends BasePredicate<DataView> {
  byteLength(byteLength: number): DataViewPredicate;
  minByteLength(byteLength: number): DataViewPredicate;
  maxByteLength(byteLength: number): DataViewPredicate;
}

const dataView: DataViewPredicate;

Usage Examples:

import ow from 'ow';

// DataView validation
const buffer = new ArrayBuffer(16);
const view = new DataView(buffer, 4, 8); // offset 4, length 8

ow(view, ow.dataView);
ow(view, ow.dataView.byteLength(8));
ow(view, ow.dataView.minByteLength(4));
ow(view, ow.dataView.maxByteLength(16));

Advanced Usage Examples

Binary Data Processing

import ow from 'ow';

// Validate binary data processing pipeline
function processBinaryData(input: unknown): Uint8Array {
  // Validate input can be converted to Uint8Array
  if (ow.isValid(input, ow.arrayBuffer)) {
    const buffer = input as ArrayBuffer;
    ow(buffer, ow.arrayBuffer.minByteLength(1));
    return new Uint8Array(buffer);
  }
  
  if (ow.isValid(input, ow.typedArray)) {
    const typedArray = input as TypedArray;
    ow(typedArray, ow.typedArray.minLength(1));
    return new Uint8Array(typedArray.buffer);
  }
  
  throw new Error('Input must be ArrayBuffer or TypedArray');
}

// Usage
const buffer = new ArrayBuffer(10);
const result = processBinaryData(buffer);
ow(result, ow.uint8Array.length(10));

Image Data Validation

import ow from 'ow';

// Validate image data (Canvas ImageData-like structure)
interface ImageData {
  data: Uint8ClampedArray;
  width: number;
  height: number;
}

function validateImageData(imageData: unknown) {
  ow(imageData, ow.object.exactShape({
    data: ow.uint8ClampedArray,
    width: ow.number.integer.positive,
    height: ow.number.integer.positive
  }));
  
  const { data, width, height } = imageData as ImageData;
  
  // RGBA data should have exactly width * height * 4 bytes
  const expectedLength = width * height * 4;
  ow(data, ow.uint8ClampedArray.length(expectedLength));
  ow(data, ow.uint8ClampedArray.byteLength(expectedLength));
}

// Usage
const imageData = {
  data: new Uint8ClampedArray(400), // 10x10 RGBA
  width: 10,
  height: 10
};

validateImageData(imageData);

Audio Buffer Validation

import ow from 'ow';

// Validate audio buffer data
interface AudioBuffer {
  sampleRate: number;
  length: number;
  numberOfChannels: number;
  channels: Float32Array[];
}

function validateAudioBuffer(audioBuffer: unknown) {
  ow(audioBuffer, ow.object.exactShape({
    sampleRate: ow.number.positive,
    length: ow.number.integer.positive,
    numberOfChannels: ow.number.integer.inRange(1, 32),
    channels: ow.array.ofType(ow.float32Array)
  }));
  
  const { channels, length, numberOfChannels } = audioBuffer as AudioBuffer;
  
  // Validate channel count matches array length
  ow(channels, ow.array.length(numberOfChannels));
  
  // Validate each channel has correct length
  channels.forEach((channel, index) => {
    ow(channel, `channel${index}`, ow.float32Array.length(length));
  });
}

Memory-Mapped Data Validation

import ow from 'ow';

// Validate memory-mapped data structures
class MemoryMappedStruct {
  private view: DataView;
  
  constructor(buffer: ArrayBuffer, offset = 0) {
    ow(buffer, ow.arrayBuffer.minByteLength(offset + 32));
    this.view = new DataView(buffer, offset, 32);
    ow(this.view, ow.dataView.byteLength(32));
  }
  
  getInt32(offset: number): number {
    ow(offset, ow.number.integer.inRange(0, 28)); // 32 - 4 bytes
    return this.view.getInt32(offset, true); // little-endian
  }
  
  setFloat64(offset: number, value: number): void {
    ow(offset, ow.number.integer.inRange(0, 24)); // 32 - 8 bytes
    ow(value, ow.number.finite);
    this.view.setFloat64(offset, value, true);
  }
}

// Usage
const buffer = new ArrayBuffer(64);
const struct = new MemoryMappedStruct(buffer, 0);
struct.setFloat64(0, 3.14159);

Install with Tessl CLI