or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-manipulation.mddatabase-management.mdindex.mdquerying-filtering.mdutility-functions.md
tile.json

tessl/npm-taffydb

JavaScript in-memory database with SQL-like query capabilities for array manipulation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/taffydb@2.7.x

To install, run

npx @tessl/cli install tessl/npm-taffydb@2.7.0

index.mddocs/

TaffyDB

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.

Package Information

  • Package Name: taffydb
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install taffydb

Core Imports

// Node.js / CommonJS
const TAFFY = require('taffydb').taffy;

// Browser (global)
// <script src="taffy.js"></script>
// TAFFY is available globally

Basic Usage

const TAFFY = require('taffydb').taffy;

// Create a database with initial data
const products = TAFFY([
  { "item": 1, "name": "Blue Ray Player", "price": 99.99 },
  { "item": 2, "name": "3D TV", "price": 1799.99 }
]);

// Query data
const item1 = products({ item: 1 });
const cheapItems = products({ price: { lt: 100 } });

// Get results
console.log(item1.first()); // Get single record
console.log(cheapItems.get()); // Get all matching records

// Update data
products({ item: 1 }).update({ price: 89.99 });

// Remove data
products({ item: 2 }).remove();

Architecture

TaffyDB is built around several key components:

  • TAFFY Constructor: Main function that creates database instances from arrays of objects
  • Database Instance: Provides methods for data management (insert, merge, sort, settings)
  • Query Interface: Fluent API for filtering, sorting, and limiting results
  • Filter System: Comprehensive operators for data matching (is, like, gt, lt, regex, etc.)
  • Static Utilities: Helper functions for type checking, object manipulation, and data comparison

Capabilities

Database Creation and Management

Core functionality for creating and managing TaffyDB database instances, including data insertion, merging, and configuration.

function TAFFY(data?: object[] | string): TaffyDatabase;

interface TaffyDatabase {
  (filter?: object | function): QueryResult;
  insert(records: object | object[] | string): QueryResult;
  merge(records: object[], key?: string, runEvent?: boolean): QueryResult;
  sort(orderString: string): boolean;
  settings(options?: object): object;
  store(storageName?: string): TaffyDatabase;
  TAFFY: boolean;
}

Database Management

Querying and Filtering

Powerful query system with SQL-like filtering capabilities, supporting complex conditions and operator combinations.

// Basic filtering
database(filterObject: object): QueryResult;
database(filterFunction: function): QueryResult;

// Filter operators available in filterObject
interface FilterObject {
  [property: string]: any | {
    is?: any;          // Exact equality
    like?: string;     // Contains substring
    lt?: number;       // Less than
    gt?: number;       // Greater than
    regex?: RegExp;    // Regular expression match
    // ... and many more operators
  };
}

Querying and Filtering

Data Manipulation

Methods for modifying, sorting, and transforming query results, including updates, deletions, data aggregation, and table joins.

interface QueryResult {
  // Data modification
  update(changes: object, runEvent?: boolean): QueryResult;
  remove(runEvent?: boolean): QueryResult;
  
  // Result retrieval
  get(): object[];
  first(): object | undefined;
  last(): object | undefined;
  count(): number;
  
  // Data processing and joins
  select(...columns: string[]): any[] | any[][];
  distinct(...columns: string[]): any[] | any[][];
  sum(...columns: string[]): number;
  min(column: string): any;
  max(column: string): any;
  join(table: TaffyDatabase | QueryResult, ...conditions: any[]): QueryResult;
}

Data Manipulation

Utility Functions

Static utility methods available on the TAFFY object for type checking, object manipulation, and data comparison operations.

// Type checking utilities
TAFFY.isString(value: any): boolean;
TAFFY.isNumber(value: any): boolean;
TAFFY.isArray(value: any): boolean;
TAFFY.isObject(value: any): boolean;
TAFFY.isFunction(value: any): boolean;

// Object manipulation utilities
TAFFY.mergeObj(obj1: object, obj2: object): object;
TAFFY.has(container: any, value: any): boolean;
TAFFY.typeOf(value: any): string;

Utility Functions

Types

// Core database interface
interface TaffyDatabase {
  // Call database as function to create queries
  (filter?: object | function): QueryResult;
  
  // Database management methods
  insert(records: object | object[] | string): QueryResult;
  merge(records: object[], key?: string, runEvent?: boolean): QueryResult;
  sort(orderString: string): boolean;
  settings(options?: object): object;
  store(storageName?: string): TaffyDatabase;
  
  // Database identifier
  TAFFY: boolean;
}

// Query result interface with chainable methods
interface QueryResult {
  // Filtering and sorting
  filter(filterObj: object | function): QueryResult;
  order(orderString: string): QueryResult;
  limit(count: number): QueryResult;
  start(offset: number): QueryResult;
  
  // Data retrieval
  get(): object[];
  first(): object | false;
  last(): object | false;
  count(): number;
  stringify(): string;
  
  // Data modification
  update(changes: object, runEvent?: boolean): QueryResult;
  remove(runEvent?: boolean): QueryResult;
  
  // Data processing and aggregation
  select(...columns: string[]): any[];
  distinct(column: string): any[];
  sum(...columns: string[]): number | number[];
  min(column: string): any;
  max(column: string): any;
  join(table: TaffyDatabase | QueryResult, ...conditions: any[]): QueryResult;
  
  // Iteration and transformation
  each(callback: function): QueryResult;
  map(callback: function): any[];
  supplant(template: string, returnArray?: boolean): string | string[];
  callback(fn: function, delay?: number): QueryResult;
}

// Database settings configuration
interface DatabaseSettings {
  template?: object;           // Default values for new records
  onInsert?: function;         // Callback for insert operations
  onUpdate?: function;         // Callback for update operations
  onRemove?: function;         // Callback for remove operations
  onDBChange?: function;       // Callback for database changes
  storageName?: string;        // localStorage key name
  forcePropertyCase?: 'lower' | 'upper' | null;  // Force property case
  cacheSize?: number;          // Query cache size
  name?: string;               // Database name
}