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
```