0
# Oboe.js
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: oboe
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install oboe`
10
11
## Core Imports
12
13
```javascript
14
// CommonJS (Node.js)
15
const oboe = require('oboe');
16
17
// ES Modules
18
import oboe from 'oboe';
19
```
20
21
For browser environments:
22
23
```html
24
<script src="oboe-browser.js"></script>
25
<!-- or via AMD -->
26
<script>
27
require(['oboe'], function(oboe) {
28
// use oboe
29
});
30
</script>
31
```
32
33
## Basic Usage
34
35
```javascript
36
const oboe = require('oboe');
37
38
// Simple GET request with progressive JSON parsing
39
oboe('https://api.example.com/users')
40
.node('!.*', function(user) {
41
// Called for each user object as it arrives
42
console.log('User:', user);
43
})
44
.done(function(users) {
45
// Called when entire JSON is parsed
46
console.log('All users loaded:', users);
47
})
48
.fail(function(error) {
49
console.error('Request failed:', error);
50
});
51
52
// Configuration object approach
53
oboe({
54
url: 'https://api.example.com/data',
55
method: 'POST',
56
body: JSON.stringify({ query: 'search term' }),
57
headers: {
58
'Content-Type': 'application/json',
59
'Authorization': 'Bearer token'
60
}
61
})
62
.node('!.results.*', handleResult)
63
.done(handleComplete);
64
```
65
66
## Architecture
67
68
Oboe.js is built around several key components:
69
70
- **Factory Function**: The main `oboe()` function creates configured instances for HTTP requests or stream processing
71
- **Instance API**: Event-driven interface providing pattern matching, lifecycle hooks, and control methods
72
- **JSONPath Engine**: Pattern matching system for selecting specific nodes in the JSON stream
73
- **Streaming Parser**: Incremental JSON parser that emits events as structure becomes available
74
- **Cross-Platform**: Unified API that works in both Node.js (with stream support) and browser environments
75
76
## Capabilities
77
78
### Factory Function
79
80
The main `oboe()` function for creating instances with various input methods and configuration options. Supports simple URL strings, configuration objects, and Node.js streams.
81
82
```javascript { .api }
83
function oboe(input: string | OboeOptions | ReadableStream): OboeInstance;
84
85
interface OboeOptions {
86
url: string;
87
method?: string;
88
body?: any;
89
headers?: Record<string, string>;
90
withCredentials?: boolean;
91
cached?: boolean;
92
}
93
```
94
95
[Factory Function](./factory.md)
96
97
### Instance API
98
99
Event-driven API for listening to JSON parsing events, including pattern-based node matching, lifecycle events, and error handling. Provides a fluent, chainable interface.
100
101
```javascript { .api }
102
interface OboeInstance {
103
// Event listeners
104
on(event: string, callback: Function): OboeInstance;
105
node(pattern: string | object, callback?: Function): OboeInstance;
106
path(pattern: string | object, callback?: Function): OboeInstance;
107
108
// Lifecycle events
109
start(callback: Function): OboeInstance;
110
done(callback: Function): OboeInstance;
111
fail(callback: Function): OboeInstance;
112
113
// Control methods
114
abort(): void;
115
forget(): void;
116
117
// Access methods
118
header(name?: string): any; // Available after 'start' event
119
root(): any; // Available after root node is found
120
source: string;
121
}
122
```
123
124
[Instance API](./instance-api.md)
125
126
### JSONPath Pattern Matching
127
128
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.
129
130
```javascript { .api }
131
// Pattern Examples:
132
// "!" - root node
133
// "!.*" - any property of root
134
// "!.users.*" - any user object
135
// "![*]" - any array element at root
136
// "!.users[0]" - first user
137
// "!.users.*.name" - name of any user
138
// "!.users.*{name email}" - users with only name and email fields
139
```
140
141
[JSONPath Patterns](./jsonpath-patterns.md)
142
143
### Stream Processing
144
145
Node.js-specific capabilities for processing readable streams, including file streams and HTTP response streams. Enables server-side JSON processing from various sources.
146
147
```javascript { .api }
148
// Node.js stream processing
149
function oboe(stream: ReadableStream): OboeInstance;
150
```
151
152
[Stream Processing](./stream-processing.md)
153
154
## Types
155
156
```javascript { .api }
157
interface OboeOptions {
158
url: string;
159
method?: string;
160
body?: any;
161
headers?: Record<string, string>;
162
withCredentials?: boolean;
163
cached?: boolean;
164
}
165
166
interface OboeInstance {
167
on(event: string, callback: Function): OboeInstance;
168
addListener(event: string, callback: Function): OboeInstance;
169
removeListener(event: string, callback?: Function): OboeInstance;
170
emit(event: string, ...args: any[]): void;
171
172
node(pattern: string | PatternMap, callback?: NodeCallback): OboeInstance;
173
path(pattern: string | PatternMap, callback?: PathCallback): OboeInstance;
174
175
start(callback: StartCallback): OboeInstance;
176
done(callback: DoneCallback): OboeInstance;
177
fail(callback: FailCallback): OboeInstance;
178
179
abort(): void;
180
forget(): void;
181
182
header(name?: string): any;
183
root(): any;
184
source: string;
185
}
186
187
interface PatternMap {
188
[pattern: string]: Function;
189
}
190
191
type NodeCallback = (node: any, path: string[], ancestors: any[]) => void;
192
type PathCallback = (path: string[], ancestors: any[]) => void;
193
type StartCallback = (statusCode: number, headers: Record<string, string>) => void;
194
type DoneCallback = (json: any) => void;
195
type FailCallback = (error: OboeError) => void;
196
197
interface OboeError {
198
thrown?: Error;
199
statusCode?: number;
200
body?: string;
201
jsonBody?: any;
202
}
203
```