0
# Factory Function
1

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

4
## Capabilities
5

6
### Main Factory Function
7

8
Creates an oboe instance with automatic input type detection.
9

10
```javascript { .api }
11
/**
12
 * Create an oboe instance for progressive JSON parsing
13
 * @param {string|object|ReadableStream} input - URL string, options object, or Node.js stream
14
 * @returns {OboeInstance} Chainable oboe instance
15
 */
16
function oboe(input?: string | OboeOptions | ReadableStream): OboeInstance;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const oboe = require('oboe');
23

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

27
// Configuration object
28
const request2 = oboe({
29
  url: 'https://api.example.com/search',
30
  method: 'POST',
31
  body: JSON.stringify({ q: 'search term' }),
32
  headers: {
33
    'Content-Type': 'application/json',
34
    'Authorization': 'Bearer token123'
35
  }
36
});
37

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

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

48
### Simple URL Constructor
49

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

52
```javascript { .api }
53
/**
54
 * Create oboe instance for GET request to URL
55
 * @param {string} url - The URL to request
56
 * @returns {OboeInstance} Configured oboe instance
57
 */
58
function oboe(url: string): OboeInstance;
59
```
60

61
### Options Constructor
62

63
Creates an oboe instance with full HTTP configuration.
64

65
```javascript { .api }
66
/**
67
 * Create oboe instance with HTTP configuration
68
 * @param {OboeOptions} options - HTTP request configuration
69
 * @returns {OboeInstance} Configured oboe instance
70
 */
71
function oboe(options: OboeOptions): OboeInstance;
72

73
interface OboeOptions {
74
  /** The URL to request */
75
  url: string;
76
  /** HTTP method (default: 'GET') */
77
  method?: string;
78
  /** Request body for POST/PUT requests */
79
  body?: any;
80
  /** HTTP headers object */
81
  headers?: Record<string, string>;
82
  /** Include credentials in CORS requests (browser only) */
83
  withCredentials?: boolean;
84
  /** Use cached response if available */
85
  cached?: boolean;
86
}
87
```
88

89
**Configuration Examples:**
90

91
```javascript
92
// POST request with JSON body
93
oboe({
94
  url: 'https://api.example.com/users',
95
  method: 'POST',
96
  body: JSON.stringify({
97
    name: 'John Doe',
98
    email: 'john@example.com'
99
  }),
100
  headers: {
101
    'Content-Type': 'application/json'
102
  }
103
});
104

105
// Authenticated request with CORS credentials
106
oboe({
107
  url: 'https://api.example.com/protected',
108
  method: 'GET',
109
  headers: {
110
    'Authorization': 'Bearer ' + token
111
  },
112
  withCredentials: true
113
});
114

115
// Cached request
116
oboe({
117
  url: 'https://api.example.com/static-data',
118
  cached: true
119
});
120
```
121

122
### Stream Constructor (Node.js)
123

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

126
```javascript { .api }
127
/**
128
 * Create oboe instance for processing a readable stream
129
 * @param {ReadableStream} stream - Node.js readable stream
130
 * @returns {OboeInstance} Configured oboe instance
131
 */
132
function oboe(stream: ReadableStream): OboeInstance;
133
```
134

135
**Stream Examples:**
136

137
```javascript
138
const fs = require('fs');
139
const http = require('http');
140

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

147
// HTTP response stream
148
http.get('http://api.example.com/stream', (res) => {
149
  oboe(res)
150
    .node('!.items.*', processItem)
151
    .fail(handleError);
152
});
153
```
154

155
### Empty Constructor
156

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

159
```javascript { .api }
160
/**
161
 * Create empty oboe instance for manual content feeding
162
 * @returns {OboeInstance} Unconfigured oboe instance
163
 */
164
function oboe(): OboeInstance;
165
```
166

167
**Manual Feeding Example:**
168

169
```javascript
170
const parser = oboe();
171

172
parser
173
  .node('!.data.*', handleDataItem)
174
  .done(handleComplete);
175

176
// Manually feed JSON chunks
177
parser.emit('data', '{"data": [');
178
parser.emit('data', '{"id": 1, "name": "item1"},');
179
parser.emit('data', '{"id": 2, "name": "item2"}');
180
parser.emit('data', ']}');
181
parser.emit('end');
182
```
183

184
## Input Type Detection
185

186
The factory function automatically detects the input type:
187

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

193
## Error Handling
194

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

197
```javascript
198
oboe('https://invalid-url.com/data.json')
199
  .fail(function(error) {
200
    console.error('Request failed:', error);
201
    // error.statusCode - HTTP status code (if applicable)
202
    // error.body - Response body (if available)
203
    // error.thrown - Original thrown error (if applicable)
204
  });
205
```
206

207
## Browser vs Node.js Differences
208

209
### Browser-specific features:
210
- CORS support via `withCredentials` option
211
- AMD module loading support
212
- Automatic cross-origin detection
213

214
### Node.js-specific features:
215
- ReadableStream processing
216
- File system stream support
217
- HTTP/HTTPS stream processing
218
- Dependency on `http-https` package
219

220
## Return Value
221

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