or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

factory.mdindex.mdinstance-api.mdjsonpath-patterns.mdstream-processing.md
tile.json

tessl/npm-oboe

Progressive JSON streaming parser that enables processing data as it arrives over HTTP without waiting for the complete response

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/oboe@1.15.x

To install, run

npx @tessl/cli install tessl/npm-oboe@1.15.0

index.mddocs/

Oboe.js

Oboe.js is a progressive JSON streaming parser that enables web applications to process JSON data as it arrives over HTTP without waiting for the complete response. It provides a streaming interface that sits between traditional download-and-parse approaches and SAX-style parsing, allowing applications to start working with JSON objects as soon as they become available in the stream.

Package Information

  • Package Name: oboe
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install oboe

Core Imports

// CommonJS (Node.js)
const oboe = require('oboe');

// ES Modules  
import oboe from 'oboe';

For browser environments:

<script src="oboe-browser.js"></script>
<!-- or via AMD -->
<script>
  require(['oboe'], function(oboe) {
    // use oboe
  });
</script>

Basic Usage

const oboe = require('oboe');

// Simple GET request with progressive JSON parsing
oboe('https://api.example.com/users')
  .node('!.*', function(user) {
    // Called for each user object as it arrives
    console.log('User:', user);
  })
  .done(function(users) {
    // Called when entire JSON is parsed
    console.log('All users loaded:', users);
  })
  .fail(function(error) {
    console.error('Request failed:', error);
  });

// Configuration object approach
oboe({
  url: 'https://api.example.com/data',
  method: 'POST',
  body: JSON.stringify({ query: 'search term' }),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token'
  }
})
  .node('!.results.*', handleResult)
  .done(handleComplete);

Architecture

Oboe.js is built around several key components:

  • Factory Function: The main oboe() function creates configured instances for HTTP requests or stream processing
  • Instance API: Event-driven interface providing pattern matching, lifecycle hooks, and control methods
  • JSONPath Engine: Pattern matching system for selecting specific nodes in the JSON stream
  • Streaming Parser: Incremental JSON parser that emits events as structure becomes available
  • Cross-Platform: Unified API that works in both Node.js (with stream support) and browser environments

Capabilities

Factory Function

The main oboe() function for creating instances with various input methods and configuration options. Supports simple URL strings, configuration objects, and Node.js streams.

function oboe(input: string | OboeOptions | ReadableStream): OboeInstance;

interface OboeOptions {
  url: string;
  method?: string;
  body?: any;
  headers?: Record<string, string>;
  withCredentials?: boolean;
  cached?: boolean;
}

Factory Function

Instance API

Event-driven API for listening to JSON parsing events, including pattern-based node matching, lifecycle events, and error handling. Provides a fluent, chainable interface.

interface OboeInstance {
  // Event listeners
  on(event: string, callback: Function): OboeInstance;
  node(pattern: string | object, callback?: Function): OboeInstance;
  path(pattern: string | object, callback?: Function): OboeInstance;
  
  // Lifecycle events
  start(callback: Function): OboeInstance;
  done(callback: Function): OboeInstance;
  fail(callback: Function): OboeInstance;
  
  // Control methods
  abort(): void;
  forget(): void;
  
  // Access methods  
  header(name?: string): any; // Available after 'start' event
  root(): any; // Available after root node is found
  source: string;
}

Instance API

JSONPath Pattern Matching

Powerful pattern matching system for selecting specific nodes and paths in the JSON stream using JSONPath-style expressions. Supports wildcards, array indexing, and field selection.

// Pattern Examples:
// "!" - root node
// "!.*" - any property of root
// "!.users.*" - any user object
// "![*]" - any array element at root
// "!.users[0]" - first user
// "!.users.*.name" - name of any user
// "!.users.*{name email}" - users with only name and email fields

JSONPath Patterns

Stream Processing

Node.js-specific capabilities for processing readable streams, including file streams and HTTP response streams. Enables server-side JSON processing from various sources.

// Node.js stream processing
function oboe(stream: ReadableStream): OboeInstance;

Stream Processing

Types

interface OboeOptions {
  url: string;
  method?: string;
  body?: any;
  headers?: Record<string, string>;
  withCredentials?: boolean;
  cached?: boolean;
}

interface OboeInstance {
  on(event: string, callback: Function): OboeInstance;
  addListener(event: string, callback: Function): OboeInstance;
  removeListener(event: string, callback?: Function): OboeInstance;
  emit(event: string, ...args: any[]): void;
  
  node(pattern: string | PatternMap, callback?: NodeCallback): OboeInstance;
  path(pattern: string | PatternMap, callback?: PathCallback): OboeInstance;
  
  start(callback: StartCallback): OboeInstance;
  done(callback: DoneCallback): OboeInstance;
  fail(callback: FailCallback): OboeInstance;
  
  abort(): void;
  forget(): void;
  
  header(name?: string): any;
  root(): any;
  source: string;
}

interface PatternMap {
  [pattern: string]: Function;
}

type NodeCallback = (node: any, path: string[], ancestors: any[]) => void;
type PathCallback = (path: string[], ancestors: any[]) => void;
type StartCallback = (statusCode: number, headers: Record<string, string>) => void;
type DoneCallback = (json: any) => void;
type FailCallback = (error: OboeError) => void;

interface OboeError {
  thrown?: Error;
  statusCode?: number;
  body?: string;
  jsonBody?: any;
}