0
# ob1
1

2
ob1 is a small TypeScript library that provides type-safe operations for working with 0-based and 1-based numeric offsets using Flow's opaque types. It prevents common off-by-one errors by enforcing type distinctions at compile time while maintaining runtime efficiency through simple numeric operations.
3

4
## Package Information
5

6
- **Package Name**: ob1
7
- **Package Type**: npm
8
- **Language**: JavaScript with Flow types
9
- **Installation**: `npm install ob1`
10

11
## Core Imports
12

13
```javascript
14
const { add, sub, get0, get1, add1, sub1, neg, add0, inc } = require("ob1");
15
```
16

17
ES Modules:
18
```javascript
19
import { add, sub, get0, get1, add1, sub1, neg, add0, inc } from "ob1";
20
```
21

22
Flow Types:
23
```javascript
24
import type { Number0, Number1 } from "ob1";
25
```
26

27
## Basic Usage
28

29
```javascript
30
const { add0, add1, add, get0, get1 } = require("ob1");
31

32
// Create typed offsets
33
const zeroBasedIndex = add0(42);  // Number0 type
34
const oneBasedLine = add1(41);    // Number1 type (42 in 1-based)
35

36
// Type-safe arithmetic
37
const sum = add(zeroBasedIndex, 3);     // Number0 + number = Number0
38
const mixed = add(zeroBasedIndex, oneBasedLine); // Number0 + Number1 = Number1
39

40
// Extract values
41
console.log(get0(sum));    // 45
42
console.log(get1(mixed));  // 85
43
```
44

45
## Architecture
46

47
ob1's architecture is built around Flow's opaque type system:
48

49
- **Opaque Types**: `Number0` and `Number1` are distinct numeric types that prevent accidental mixing
50
- **Type Safety**: Operations preserve offset semantics through overloaded function signatures
51
- **Runtime Efficiency**: All operations are simple numeric calculations with zero runtime overhead
52
- **Compile-time Validation**: Flow prevents unsafe operations like adding two 1-based offsets
53

54
## Capabilities
55

56
### Type System
57

58
Core opaque types for representing different offset bases.
59

60
```javascript { .api }
61
// 0-based offset type (for array indices, positions starting from 0)
62
export opaque type Number0 = number;
63

64
// 1-based offset type (for line numbers, columns starting from 1)  
65
export opaque type Number1 = number;
66
```
67

68
### Arithmetic Operations
69

70
Type-safe addition and subtraction with automatic type propagation.
71

72
```javascript { .api }
73
/**
74
 * Add two offsets or numbers with type-safe result types
75
 * @param a - First operand (Number0, Number1, or number)
76
 * @param b - Second operand (Number0, Number1, or number)  
77
 * @returns Result preserving appropriate offset type
78
 */
79
declare function add(a: Number1, b: number): Number1;
80
declare function add(a: number, b: Number1): Number1;
81
declare function add(a: Number0, b: number): Number0;
82
declare function add(a: number, b: Number0): Number0;
83
declare function add(a: Number1, b: Number0): Number1;
84
declare function add(a: Number0, b: Number1): Number1;
85
declare function add(a: Number0, b: Number0): Number0;
86

87
/**
88
 * Subtract a number or 0-based offset from a 1/0-based offset
89
 * @param a - Minuend (Number0, Number1, or number)
90
 * @param b - Subtrahend (Number0, Number1, or number)
91
 * @returns Result with appropriate offset type
92
 */
93
declare function sub(a: Number1, b: number): Number1;
94
declare function sub(a: Number0, b: number): Number0;
95
declare function sub(a: number, b: Number0): Number0;
96
declare function sub(a: Number0, b: number): Number0;
97
declare function sub(a: Number1, b: Number0): Number1;
98
declare function sub(a: Number0, b: Number0): Number0;
99
declare function sub(a: Number1, b: Number1): Number0;
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
const { add0, add1, add, sub, get0, get1 } = require("ob1");
106

107
const index = add0(5);     // Number0
108
const line = add1(10);     // Number1
109

110
// Safe additions
111
const newIndex = add(index, 3);        // Number0 + number = Number0
112
const newLine = add(line, index);      // Number1 + Number0 = Number1
113

114
// Safe subtractions  
115
const diff = sub(line, line);          // Number1 - Number1 = Number0 (distance)
116
const prevIndex = sub(index, 2);       // Number0 - number = Number0
117

118
console.log(get0(newIndex));  // 8
119
console.log(get1(newLine));   // 16
120
console.log(get0(diff));      // 0
121
```
122

123
### Type Casting and Extraction
124

125
Functions for creating offset types and extracting underlying values.
126

127
```javascript { .api }
128
/**
129
 * Cast a number to a 0-based offset
130
 * @param x - Number to cast
131
 * @returns Number0 offset type
132
 */
133
function add0(x: number): Number0;
134

135
/**
136
 * Get the underlying number of a 0-based offset, casting away the opaque type
137
 * @param x - Number0 offset or null/undefined
138
 * @returns Underlying number value or null/undefined
139
 */
140
declare function get0(x: Number0): number;
141
declare function get0(x: void | null): void | null;
142

143
/**
144
 * Get the underlying number of a 1-based offset, casting away the opaque type
145
 * @param x - Number1 offset or null/undefined  
146
 * @returns Underlying number value or null/undefined
147
 */
148
declare function get1(x: Number1): number;
149
declare function get1(x: void | null): void | null;
150
```
151

152
### Offset Conversion
153

154
Functions for converting between 0-based and 1-based offset types.
155

156
```javascript { .api }
157
/**
158
 * Add 1 to a 0-based offset, converting it to 1-based
159
 * @param x - Number0 offset or regular number
160
 * @returns Number1 offset (input + 1)
161
 */
162
function add1(x: Number0 | number): Number1;
163

164
/**
165
 * Subtract 1 from a 1-based offset, converting it to 0-based  
166
 * @param x - Number1 offset
167
 * @returns Number0 offset (input - 1)
168
 */
169
function sub1(x: Number1): Number0;
170
```
171

172
**Usage Examples:**
173

174
```javascript
175
const { add0, add1, sub1, get0, get1 } = require("ob1");
176

177
// Array index to line number conversion
178
const arrayIndex = add0(4);           // 5th element (0-based)
179
const lineNumber = add1(arrayIndex);  // Line 5 (1-based)
180

181
// Line number to array index conversion  
182
const currentLine = add1(42);         // Line 43 (1-based)
183
const arrayPos = sub1(currentLine);   // Index 42 (0-based)
184

185
console.log(get0(arrayIndex));  // 4
186
console.log(get1(lineNumber));  // 5
187
console.log(get0(arrayPos));    // 42
188
```
189

190
### Utility Operations
191

192
Additional operations for incrementing and negating offsets.
193

194
```javascript { .api }
195
/**
196
 * Increment a 0-based or 1-based offset by 1
197
 * @param a - Offset to increment (Number0 or Number1)
198
 * @returns Same offset type incremented by 1
199
 */
200
declare function inc(a: Number0): Number0;
201
declare function inc(a: Number1): Number1;
202

203
/**
204
 * Negate a 0-based offset
205
 * @param x - Number0 offset to negate
206
 * @returns Negated Number0 offset
207
 */
208
function neg(x: Number0): Number0;
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
const { add0, add1, inc, neg, get0, get1 } = require("ob1");
215

216
const index = add0(5);
217
const line = add1(10);
218

219
// Increment operations preserve type
220
const nextIndex = inc(index);  // Number0: 6
221
const nextLine = inc(line);    // Number1: 11
222

223
// Negation (only for Number0)
224
const negative = neg(index);   // Number0: -5
225

226
console.log(get0(nextIndex)); // 6  
227
console.log(get1(nextLine));  // 11
228
console.log(get0(negative));  // -5
229
```
230

231
## Type Safety Features
232

233
### Allowed Operations
234

235
ob1's type system allows these safe combinations:
236

237
- `Number0 + Number0 = Number0` - Adding two 0-based offsets
238
- `Number0 + Number1 = Number1` - Adding 0-based to 1-based yields 1-based
239
- `Number1 + Number0 = Number1` - Adding 1-based to 0-based yields 1-based  
240
- `Number1 - Number1 = Number0` - Distance between 1-based positions
241
- `Number0/Number1 + number` - Adding plain numbers preserves offset type
242

243
### Prevented Operations
244

245
Flow will prevent these unsafe operations at compile time:
246

247
- `Number1 + Number1` - Adding two 1-based offsets is mathematically meaningless
248
- `Number0 - Number1` - Would create negative 0-based offsets
249
- `get0(Number1)` - Cross-type extraction
250
- `get1(Number0)` - Cross-type extraction  
251
- `add1(Number1)` - Converting already 1-based offset
252
- `sub1(Number0)` - Converting already 0-based offset
253
- Direct arithmetic (`offset + 1`, `offset - 1`) - Must use provided functions
254

255
## Error Handling
256

257
ob1 operations are purely mathematical and do not throw exceptions. Invalid combinations are prevented at compile time through Flow's type system rather than runtime checks.
258

259
For null/undefined handling, the `get0` and `get1` functions have overloaded signatures that preserve null/undefined values:
260

261
```javascript
262
get0(null);      // returns null
263
get0(undefined); // returns undefined  
264
get1(null);      // returns null
265
get1(undefined); // returns undefined
266
```