tessl/npm-oboe

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

1.11x

Overview

Eval results

Files

Factory Function

Name: tessl/npm-oboe
Rating: 0.94 (1 reviews)
Author: tessl

The main oboe() function creates configured instances for processing JSON streams from various sources including HTTP URLs, configuration objects, and Node.js readable streams.

Capabilities

Main Factory Function

Creates an oboe instance with automatic input type detection.

/**
 * Create an oboe instance for progressive JSON parsing
 * @param {string|object|ReadableStream} input - URL string, options object, or Node.js stream
 * @returns {OboeInstance} Chainable oboe instance
 */
function oboe(input?: string | OboeOptions | ReadableStream): OboeInstance;

Usage Examples:

const oboe = require('oboe');

// Simple URL string (GET request)
const request1 = oboe('https://api.example.com/data.json');

// Configuration object
const request2 = oboe({
  url: 'https://api.example.com/search',
  method: 'POST',
  body: JSON.stringify({ q: 'search term' }),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123'
  }
});

// Node.js stream (server-side only)
const fs = require('fs');
const fileStream = fs.createReadStream('data.json');
const request3 = oboe(fileStream);

// Empty call for manual content feeding
const request4 = oboe();
// Content can be fed via: request4.emit('data', jsonChunk);

Simple URL Constructor

Creates an oboe instance for a simple GET request to the specified URL.

/**
 * Create oboe instance for GET request to URL
 * @param {string} url - The URL to request
 * @returns {OboeInstance} Configured oboe instance
 */
function oboe(url: string): OboeInstance;

Options Constructor

Creates an oboe instance with full HTTP configuration.

/**
 * Create oboe instance with HTTP configuration
 * @param {OboeOptions} options - HTTP request configuration
 * @returns {OboeInstance} Configured oboe instance
 */
function oboe(options: OboeOptions): OboeInstance;

interface OboeOptions {
  /** The URL to request */
  url: string;
  /** HTTP method (default: 'GET') */
  method?: string;
  /** Request body for POST/PUT requests */
  body?: any;
  /** HTTP headers object */
  headers?: Record<string, string>;
  /** Include credentials in CORS requests (browser only) */
  withCredentials?: boolean;
  /** Use cached response if available */
  cached?: boolean;
}

Configuration Examples:

// POST request with JSON body
oboe({
  url: 'https://api.example.com/users',
  method: 'POST',
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john@example.com'
  }),
  headers: {
    'Content-Type': 'application/json'
  }
});

// Authenticated request with CORS credentials
oboe({
  url: 'https://api.example.com/protected',
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ' + token
  },
  withCredentials: true
});

// Cached request
oboe({
  url: 'https://api.example.com/static-data',
  cached: true
});

Stream Constructor (Node.js)

Creates an oboe instance that processes a Node.js readable stream.

/**
 * Create oboe instance for processing a readable stream
 * @param {ReadableStream} stream - Node.js readable stream
 * @returns {OboeInstance} Configured oboe instance
 */
function oboe(stream: ReadableStream): OboeInstance;

Stream Examples:

const fs = require('fs');
const http = require('http');

// File stream
const fileStream = fs.createReadStream('large-data.json');
oboe(fileStream)
  .node('!.records.*', processRecord)
  .done(allRecordsProcessed);

// HTTP response stream
http.get('http://api.example.com/stream', (res) => {
  oboe(res)
    .node('!.items.*', processItem)
    .fail(handleError);
});

Empty Constructor

Creates an oboe instance without a predefined source, allowing manual content feeding.

/**
 * Create empty oboe instance for manual content feeding
 * @returns {OboeInstance} Unconfigured oboe instance
 */
function oboe(): OboeInstance;

Manual Feeding Example:

const parser = oboe();

parser
  .node('!.data.*', handleDataItem)
  .done(handleComplete);

// Manually feed JSON chunks
parser.emit('data', '{"data": [');
parser.emit('data', '{"id": 1, "name": "item1"},');
parser.emit('data', '{"id": 2, "name": "item2"}');
parser.emit('data', ']}');
parser.emit('end');

Input Type Detection

The factory function automatically detects the input type:

String: Treated as URL for GET request
Object with url property: Treated as options configuration
Object with stream-like properties: Treated as Node.js readable stream (Node.js only)
Undefined/null: Creates empty instance for manual feeding

Error Handling

The factory function itself does not throw errors - all errors are reported through the instance's fail event:

oboe('https://invalid-url.com/data.json')
  .fail(function(error) {
    console.error('Request failed:', error);
    // error.statusCode - HTTP status code (if applicable)
    // error.body - Response body (if available)
    // error.thrown - Original thrown error (if applicable)
  });

Browser vs Node.js Differences

Browser-specific features:

CORS support via withCredentials option
AMD module loading support
Automatic cross-origin detection

Node.js-specific features:

ReadableStream processing
File system stream support
HTTP/HTTPS stream processing
Dependency on http-https package

Return Value

All factory function variants return an OboeInstance that provides the full event-driven API for progressive JSON parsing.

Install with Tessl CLI

npx tessl i tessl/npm-oboe