Retrieves rows from the specified table and rerenders your component. If notify is ommitted, the component will rerender for all events on the specified table. Supported notify events are: 'onInsert' | 'onUpdate' | 'onDelete'. If a filtering function is not provided to the where parameter, this will return all rows in the table.

use(where?: Partial<T> | ((row: TableRow<T>) => boolean) | null, notify?: ['onInsert' | 'onUpdate' | 'onDelete']): TableRow<T>[]

// returns all rows from the cats table
// will rerender the component whenever any change occurs to the table
import { tables } from './store';
const rows = tables.cats.use();

// returns all rows from the cats table where the name is "Cleo"
// will rerender the component whenever a new row is inserted or deleted
import { tables } from './store';
const rows = tables.cats.use(row => row.name === 'Cleo', ['onInsert', 'onDelete']);

Retrieves a row from the specified table and rerenders your component. If notify is ommitted, the component will rerender for all events on the specified row. Supported notify events are: 'onUpdate' | 'onDelete'.

useById(_id: number, notify?: ['onUpdate', 'onDelete']): TableRow<T> | undefined

// returns the row with an autogenerated _id entry of 10
// will rerender the component whenever the row is updated or deleted
import { tables } from './store';
const row = tables.cats.useById(10);

// returns the row with an autogenerated _id entry of 10
// will rerender the component whenever the row is updated
import { tables } from './store';
const row = tables.cats.useById(10, ['onUpdate']);

Receives a query function and loads the data into the specified table, returning the data, status, and any error messages.

useLoadData(queryFn: () => Promise<T[]> | undefined, options?: object): { data: TableRow<T>[]; status: FetchStatus; error: string | null };

export function MyComponent() {
    const {
        data: myData,
        status,
        error,
    } = tables.folders.useLoadData(
        // custom query function returns a promise for retrieving the data
        async () => {
            const { data } = await getData<MyDataType[]>('/mydata/endpoint', 'GET');
            return data;
        },
        {
            refreshOn: [],
            refreshMode: 'append',
            fetchOnMount: !singles.dataLoaded.get(),
            onSuccess: () => singles.dataLoaded.set(true),
            filter: (row) => row.value > 10,
        }
    );

    if (status === 'loading') {
        return <div>Loading</div>;
    }

    if (error) {
        return <div>{error}</div>;
    }

    return (
        <ul>
            {myData.map(d => <li key={d.key}>{d.value}</li>)}
        </ul>
    );
}
    

Retrieves matching rows from the specified table without causing your component to rerender.

find(where?: Partial<T> | ((v: TableRow<T>) => boolean)): TableRow<T>[]

// return all rows from the cats table
import { tables } from './store';
const rows = tables.cats.find();

// return all rows from the cats table named "PJ"
import { tables } from './store';
const rows = tables.cats.find({ name: "PJ" });

// return all rows from the cats table with an age greater than 7
import { tables } from './store';
const rows = tables.cats.find(cat => cat.age > 7);

Retrieves the first matching row from the specified table without causing your component to rerender.

findOne(where?: Partial<T> | ((v: TableRow<T>) => boolean)): TableRow<T> | undefined

// returns the first row where the name is "PJ"
import { tables } from './store';
const row = tables.cats.findOne({ name: 'PJ' })

// returns the first row where the age is greater than 7
import { tables } from './store';
const row = tables.cats.findOne(cat => cat.age > 7)

Retrieves the row matching the provided _id from the specified table without causing your component to rerender.

findById(_id: number): TableRow<T> | undefined

// returns the row with a _id of 10
import { tables } from './store';
const row = tables.cats.findById(10);

Retrieves each row in the table one at a time without causing your component to rerender

scan(fn: (row: TableRow<T>, i: number) => boolean | void): void

// return the first three rows in the table
import { tables } from './store';
const rows = [];
tables.cats.scan((cat, i) => {
    if (i == 3) {
        return false;
    }
    rows.push(cat);
});

Returns the number of matching rows in the specified.

count(where?: Partial<T> | ((v: TableRow<T>) => boolean)): number

// count all rows from the cats table
import { tables } from './store';
const n = tables.cats.count();

// count all rows from the cats table named "PJ"
import { tables } from './store';
const n = tables.cats.count({ name: "PJ" });

// count all rows from the cats table with an age greater than 7
import { tables } from './store';
const n = tables.cats.count(cat => cat.age > 7);

Inserts a new row into the specified table. The user does not need to provide the _id property as this will be handled automatically. This will return the newly inserted row or undefined if the user has a beforeInsertTrigger attached to the table that aborts the insert.

insertOne(row: T): TableRow<T> | undefined

// returns the newly insertedRow
import { tables } from './store';
const row = tables.cats.insertOne({ name: 'Cleo', age: 7 });

Inserts multiple rows into the specified table. The user does not need to provide the _id property for each row as this will be handled automatically. This will return the newly inserted rows. Any attached triggers (e.g., beforeInsertTrigger) will be fired for each row. By default, components with a matching use() hook will only be rerendered after all rows are inserted. To override this behavior, pass false as the second argument, instructing Trigger to rerender components on each insert, which is the same behavior as manually calling insertRow() multiple times.

insertMany(rows: T[], batchNotify?: boolean): TableRow<T>[]

// returns the newly inserted rows; components will rerender after all rows are inserted
import { tables } from './store';
const rows = tables.cats.insertMany([ { name: 'Cleo', age: 7 }, { name: 'PJ', age: 6 } ]);

// returns the newly inserted rows; components will rerender as each row is inserted
import { tables } from './store';
const rows = tables.cats.insertMany([ { name: 'Cleo', age: 7 }, { name: 'PJ', age: 6 } ], false);

A trigger function that can be attached to a table before a new row is inserted.

onBeforeInsert(fn: (row: TableRow<T>) => TableRow<T> | void | boolean): void

// when inserting a row, change all names to lowercase and add 1 to the age
import { tables } from './store';
tables.cats.onBeforeInsert(cat => {
    cat.name = cat.name.toLowerCase();
    cat.age += 1;
    return cat;
});

A trigger function that can be attached to a table after a new row is inserted.

onAfterInsert(fn: (row: TableRow<T>) => void): void

// the newly insert row is used to insert a row into another table
import { tables } from './store';
tables.cats.onAfterInsert(cat => {
    tables.coolCats.insertOne({ name: cat.name, age: cat.age });
});

Will delete the first matching row only, returning true if a row was deleted and false if a row was not deleted. The primary use of this function is for when the user knows the _id of the row to be deleted.

deleteOne(Partial<T> | ((row: TableRow<T>) => boolean)): boolean

// delete the first cat found with the name "PJ"
import { tables } from './store';
tables.cats.deleteOne({ name: 'PJ' });

// delete the first cat found whose age is > 7
import { tables } from './store';
tables.cats.deleteOne(cat => cat.age > 7);

Will delete the row matching the provided _id, returning true if a row was deleted and false if a row was not deleted. The primary use of this function is for when the user knows the _id of the row to be deleted.

deleteById(_id: number): boolean

// delete the cat with a _id entry of 3
import { tables } from './store';
tables.cats.deleteById(3);

Will delete all rows matching the object or function passed to the where parameter. If where is undefined or null, all rows in the table will be deleted.

deleteMany(where?: Partial<T> | ((row: TableRow<T>) => boolean) | null, batchNotify?: boolean): number

// delete all rows from the coolcats table
import { tables } from './store';
tables.coolcats.deleteMany();

// delete all rows from the cats table named "PJ" and are 7 years old
import { tables } from './store';
tables.cats.deleteMany({ name: "PJ", age: 7 });

// delete all rows from the cats table with an age greater than 7
import { tables } from './store';
tables.cats.deleteMany(cat => cat.age > 7);

A trigger function that can be attached to a table before a row is deleted.

onBeforeDelete(fn: (row: TableRow<T>) => boolean | void): void

// prevent deletion of cats named "Cleo"
import { tables } from './store';
tables.cats.onBeforeDelete(cat => {
    if (cat.name === "Cleo") {
        return false // prevent deletion
    }
)};

A trigger function that can be attached to a table after a row is deleted.

onAfterDelete(fn: (row: TableRow<T>) => void): void

// the deleted row is used to delete a row from another table
import { tables } from './store';
tables.cats.onAfterDelete(cat => {
    tables.coolCats.deleteRow({ name: cat.name });
});

Update an existing row in the specified table. The user needs to know the _id of the row to be updated.

updateById(_id: number, setValue: Partial<T> | ((row: TableRow<T>) => Partial<T>), render?: boolean): TableRow<T> | undefined

// change the name of the cat with _id entry of 10 to "Pickles"
import { tables } from './store';
const row = tables.cats.updateById(10, { name: 'Pickles' });

// increment the age of the cat with _id entry of 10
import { tables } from './store';
const row = tables.cats.updateById(10, cat => ({ age: cat.age++ }));

A function that will update all rows matching the object or function passed to the where parameter. If where is undefined or null, all rows in the table will be updated.

updateMany(setValue: Partial<T> | ((row: TableRow<T>) => Partial<T>), where?: Partial<T> | ((row: TableRow<T>) => boolean) | null, options?: object): TableRow<T>[]

// update all cats to be named "PJ"
import { tables } from './store';
tables.cats.updateMany({ name: "PJ" });

// increment the age of all cats who are named "PJ" 
import { tables } from './store';
tables.cats.updateMany(cat => ({ age: cat.age++ }), { name: "PJ" });

// change the name of all cats named "PJ" and older than 7 to "Old PJ"; components will rerender as each row is updated
import { tables } from './store';
tables.cats.updateMany({ name: "Old PJ" }, cat => cat.age > 7 && cat.name == "PJ", false);

A trigger function that can be attached to a table before a row is updated.

onBeforeUpdate(fn: (currentValue: TableRow<T>, newValue: TableRow<T>) => TableRow<T> | void | boolean): void

// prevent updates to cats named "Cleo"
import { tables } from './store';
tables.cats.onBeforeUpdate(cat => {
    if (cat.name === "Cleo") {
        return false // prevent updating
    }
)};

A trigger function that can be attached to a table after a row is updated.

onAfterUpdate(fn: (previousValue: TableRow<T>, newValue: TableRow<T>) => void): void

// the updated row is used to update a row from another table
import { tables } from './store';
tables.cats.onAfterUpdate((previousValue, newValue) => {
    if (newValue.age > previousValue.age) {
        tables.cats.updateRow(newValue._id, { name: "Old Cat" });
    }
});

Returns the column names for the specified table (including the _id column)

columnNames(): (keyof TableRow<T>)[]

// get column names for the cats table
import { tables } from './store';
const columns = tables.cats.columnNames();

Prints the specified table to the console to view its contents. Some browsers require the developer console to be open for the table to print; otherwise, an object will be logged instead. You can copy this object and manually type console.table() into the console if needed.

print(where?: Partial<T> | ((row: TableRow<T>) => boolean) | null, n?: number): void

// print the first 50 rows from the cats table to the console
import { tables } from './store';
tables.cats.print();

// print the first 100 rows from the cats table to the console
import { tables } from './store';
tables.cats.print(null, 100);

// print all rows from the cats table to the console where the age is greater than 7
import { tables } from './store';
tables.cats.print(cat => cat.age > 7, -1);

// print the first 50 rows from the cats table to the console where the name is "PJ"
import { tables } from './store';
tables.cats.print({ name: "PJ" });

Returns rows from specified table as a JSON string.

toJSON(index?: boolean, where?: Partial<T> | ((row: TableRow<T>) => boolean) | null, n?: number): string

// return the first 50 rows from the cats table as a JSON string, and omit the _id
import { tables } from './store';
const jsonString = tables.cats.toJSON();

// return the first 100 rows from the cats table as a JSON string, and omit the _id
import { tables } from './store';
const jsonString = tables.cats.toJSON(false, null, 100);

// return all rows from the cats table as a JSON string where the age is greater than 7, and include the _id
import { tables } from './store';
const jsonString = tables.cats.toJSON(true, cat => cat.age > 7, -1);

// return the first 50 rows from the cats table as a JSON string where the name is "PJ", and omit the _id
import { tables } from './store';
const jsonString = tables.cats.toJSON(false, { name: "PJ" });