0
# TaffyDB
1
2
TaffyDB is a JavaScript in-memory database that brings powerful database features into JavaScript applications. It provides SQL-like querying capabilities for arrays of JavaScript objects, enabling developers to easily manipulate, filter, sort, and aggregate data without external database dependencies.
3
4
## Package Information
5
6
- **Package Name**: taffydb
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install taffydb`
10
11
## Core Imports
12
13
```javascript
14
// Node.js / CommonJS
15
const TAFFY = require('taffydb').taffy;
16
17
// Browser (global)
18
// <script src="taffy.js"></script>
19
// TAFFY is available globally
20
```
21
22
## Basic Usage
23
24
```javascript
25
const TAFFY = require('taffydb').taffy;
26
27
// Create a database with initial data
28
const products = TAFFY([
29
{ "item": 1, "name": "Blue Ray Player", "price": 99.99 },
30
{ "item": 2, "name": "3D TV", "price": 1799.99 }
31
]);
32
33
// Query data
34
const item1 = products({ item: 1 });
35
const cheapItems = products({ price: { lt: 100 } });
36
37
// Get results
38
console.log(item1.first()); // Get single record
39
console.log(cheapItems.get()); // Get all matching records
40
41
// Update data
42
products({ item: 1 }).update({ price: 89.99 });
43
44
// Remove data
45
products({ item: 2 }).remove();
46
```
47
48
## Architecture
49
50
TaffyDB is built around several key components:
51
52
- **TAFFY Constructor**: Main function that creates database instances from arrays of objects
53
- **Database Instance**: Provides methods for data management (insert, merge, sort, settings)
54
- **Query Interface**: Fluent API for filtering, sorting, and limiting results
55
- **Filter System**: Comprehensive operators for data matching (is, like, gt, lt, regex, etc.)
56
- **Static Utilities**: Helper functions for type checking, object manipulation, and data comparison
57
58
## Capabilities
59
60
### Database Creation and Management
61
62
Core functionality for creating and managing TaffyDB database instances, including data insertion, merging, and configuration.
63
64
```javascript { .api }
65
function TAFFY(data?: object[] | string): TaffyDatabase;
66
67
interface TaffyDatabase {
68
(filter?: object | function): QueryResult;
69
insert(records: object | object[] | string): QueryResult;
70
merge(records: object[], key?: string, runEvent?: boolean): QueryResult;
71
sort(orderString: string): boolean;
72
settings(options?: object): object;
73
store(storageName?: string): TaffyDatabase;
74
TAFFY: boolean;
75
}
76
```
77
78
[Database Management](./database-management.md)
79
80
### Querying and Filtering
81
82
Powerful query system with SQL-like filtering capabilities, supporting complex conditions and operator combinations.
83
84
```javascript { .api }
85
// Basic filtering
86
database(filterObject: object): QueryResult;
87
database(filterFunction: function): QueryResult;
88
89
// Filter operators available in filterObject
90
interface FilterObject {
91
[property: string]: any | {
92
is?: any; // Exact equality
93
like?: string; // Contains substring
94
lt?: number; // Less than
95
gt?: number; // Greater than
96
regex?: RegExp; // Regular expression match
97
// ... and many more operators
98
};
99
}
100
```
101
102
[Querying and Filtering](./querying-filtering.md)
103
104
### Data Manipulation
105
106
Methods for modifying, sorting, and transforming query results, including updates, deletions, data aggregation, and table joins.
107
108
```javascript { .api }
109
interface QueryResult {
110
// Data modification
111
update(changes: object, runEvent?: boolean): QueryResult;
112
remove(runEvent?: boolean): QueryResult;
113
114
// Result retrieval
115
get(): object[];
116
first(): object | undefined;
117
last(): object | undefined;
118
count(): number;
119
120
// Data processing and joins
121
select(...columns: string[]): any[] | any[][];
122
distinct(...columns: string[]): any[] | any[][];
123
sum(...columns: string[]): number;
124
min(column: string): any;
125
max(column: string): any;
126
join(table: TaffyDatabase | QueryResult, ...conditions: any[]): QueryResult;
127
}
128
```
129
130
[Data Manipulation](./data-manipulation.md)
131
132
### Utility Functions
133
134
Static utility methods available on the TAFFY object for type checking, object manipulation, and data comparison operations.
135
136
```javascript { .api }
137
// Type checking utilities
138
TAFFY.isString(value: any): boolean;
139
TAFFY.isNumber(value: any): boolean;
140
TAFFY.isArray(value: any): boolean;
141
TAFFY.isObject(value: any): boolean;
142
TAFFY.isFunction(value: any): boolean;
143
144
// Object manipulation utilities
145
TAFFY.mergeObj(obj1: object, obj2: object): object;
146
TAFFY.has(container: any, value: any): boolean;
147
TAFFY.typeOf(value: any): string;
148
```
149
150
[Utility Functions](./utility-functions.md)
151
152
## Types
153
154
```javascript { .api }
155
// Core database interface
156
interface TaffyDatabase {
157
// Call database as function to create queries
158
(filter?: object | function): QueryResult;
159
160
// Database management methods
161
insert(records: object | object[] | string): QueryResult;
162
merge(records: object[], key?: string, runEvent?: boolean): QueryResult;
163
sort(orderString: string): boolean;
164
settings(options?: object): object;
165
store(storageName?: string): TaffyDatabase;
166
167
// Database identifier
168
TAFFY: boolean;
169
}
170
171
// Query result interface with chainable methods
172
interface QueryResult {
173
// Filtering and sorting
174
filter(filterObj: object | function): QueryResult;
175
order(orderString: string): QueryResult;
176
limit(count: number): QueryResult;
177
start(offset: number): QueryResult;
178
179
// Data retrieval
180
get(): object[];
181
first(): object | false;
182
last(): object | false;
183
count(): number;
184
stringify(): string;
185
186
// Data modification
187
update(changes: object, runEvent?: boolean): QueryResult;
188
remove(runEvent?: boolean): QueryResult;
189
190
// Data processing and aggregation
191
select(...columns: string[]): any[];
192
distinct(column: string): any[];
193
sum(...columns: string[]): number | number[];
194
min(column: string): any;
195
max(column: string): any;
196
join(table: TaffyDatabase | QueryResult, ...conditions: any[]): QueryResult;
197
198
// Iteration and transformation
199
each(callback: function): QueryResult;
200
map(callback: function): any[];
201
supplant(template: string, returnArray?: boolean): string | string[];
202
callback(fn: function, delay?: number): QueryResult;
203
}
204
205
// Database settings configuration
206
interface DatabaseSettings {
207
template?: object; // Default values for new records
208
onInsert?: function; // Callback for insert operations
209
onUpdate?: function; // Callback for update operations
210
onRemove?: function; // Callback for remove operations
211
onDBChange?: function; // Callback for database changes
212
storageName?: string; // localStorage key name
213
forcePropertyCase?: 'lower' | 'upper' | null; // Force property case
214
cacheSize?: number; // Query cache size
215
name?: string; // Database name
216
}
217
```