Skip to main content

Database <T>

The main database class.

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

  • Type parameters

    • T: PersistenceAdapterMode

    Parameters

    Returns Database<T>

Properties

autosave

autosave: boolean = false

autosaveHandle

autosaveHandle: number | Timer = null

autosaveInterval

autosaveInterval: number = 5000

readonlycollections

collections: Collection<any>[] = []

readonlydatabaseVersion

databaseVersion: 1.5 = 1.5

readonlyengineVersion

engineVersion: 1.5 = 1.5

readonlyfileName

fileName: string = 'database.db'

fire

fire: <T>(event: Event<EventDetail<T>>) => boolean = ...

Type declaration

ignoreAutosave

ignoreAutosave: boolean = false

isIncremental

isIncremental: boolean = false

off

off: <T>(type: EventName<T>, callback: Listener<T>, options?: boolean | EventListenerOptions) => void = ...

Type declaration

    • <T>(type: EventName<T>, callback: Listener<T>, options?: boolean | EventListenerOptions): void

on

on: <T>(type: T, listener: Listener<T>, options?: boolean | AddEventListenerOptions) => void = ...

Type declaration

    • <T>(type: T, listener: Listener<T>, options?: boolean | AddEventListenerOptions): void

options

options: IDatabaseOptions<T>

persistenceAdapter

persistenceAdapter: PersistenceAdapter<T> = null

save

save: () => Promise<boolean> = ...

Type declaration

    • (): Promise<boolean>

    • Handles manually saving to file system, local storage, or adapter (such as indexed-db) This method utilizes database configuration options (if provided) to determine which persistence method to use, or environment detection (if configuration was not provided).

      If you are configured with autosave, you do not need to call this method yourself.

      @example
      db.saveDatabase(function(err) {
        if (err) {
          console.log("error : " + err);
        }
        else {
          console.log("database saved.");
        }
      });

      Returns Promise<boolean>

throttledSaves

throttledSaves: boolean = true

toJson

toJson: { (options?: { serializationMethod: Normal }): string; (options?: { serializationMethod: Pretty }): string; (options?: { serializationMethod: Destructured }): string[] } = ...

Type declaration

    • (options?: { serializationMethod: Normal }): string
    • (options?: { serializationMethod: Pretty }): string
    • (options?: { serializationMethod: Destructured }): string[]

    • Serialize database to a string which can be loaded via loadJSON

      Parameters

      • optionaloptions: { serializationMethod: Normal }

      Returns string

      Stringified representation of the database database.

    • Parameters

      • optionaloptions: { serializationMethod: Pretty }

      Returns string

    • Parameters

      • optionaloptions: { serializationMethod: Destructured }

      Returns string[]

readonlyverbose

verbose: boolean

Methods

addCollection

  • Adds a collection to the database.

    Type parameters

    • P: object

    Parameters

    • name: string

      name of collection to add

    • optionaloptions: Partial<ICollectionOptions<P>>

      options to configure collection with.

    Returns Collection<P>

addEventListener

  • addEventListener<T>(type: T, listener: Listener<T>, options?: boolean | AddEventListenerOptions): void

  • Type parameters

    • T: EventName<any, T>

    Parameters

    • type: T
    • listener: Listener<T>
    • optionaloptions: boolean | AddEventListenerOptions

    Returns void

autosaveClearFlags

  • autosaveClearFlags(): void

  • autosaveClearFlags - resets dirty flags on all collections. Called from saveDatabase() after db is saved.

    Returns void

autosaveDirty

  • autosaveDirty(): boolean

  • autosaveDirty - check whether any collections are ‘dirty’ meaning we need to save (entire) database

    Returns boolean

    true if database has changed since last autosave, false if not.

autosaveDisable

  • autosaveDisable(): void

  • autosaveDisable - stop the autosave interval timer.

    Returns void

autosaveEnable

  • autosaveEnable(): Promise<void>

  • autosaveEnable - begin a javascript interval to periodically save the database.

    Returns Promise<void>

clearChanges

  • clearChanges(): void

  • (Changes API) : clears all the changes in all collections.

    Returns void

close

  • close(): Promise<unknown>

  • Emits the close event. In autosave scenarios, if the database is dirty, this will save and disable timer. Does not actually destroy the db.

    Returns Promise<unknown>

configureOptions

  • configureOptions(options: Partial<IDatabaseOptions<T>>, initialConfig?: boolean): void

  • Allows reconfiguring database options

    Parameters

    • options: Partial<IDatabaseOptions<T>>

      configuration options to apply to db object

    • initialConfig: boolean = false

      (internal) true is passed when ctor is invoking

    Returns void

copy

  • Copies ‘this’ database into a new Database instance. Object references are shared to make it lightweight enough.

    Parameters

    Returns Database<Default>

deleteDatabase

  • deleteDatabase(): Promise<void>

  • Handles deleting a database from file system, localStorage, or adapter (indexed-db) This method utilizes database configuration options (if provided) to determine which persistence method to use, or environment detection (if configuration was not provided).

    Returns Promise<void>

deserializeCollection

  • Collection level utility function to deserializes a destructured collection.

    Type parameters

    • P: object

    Parameters

    • destructuredSource: string | string[] | Database<any>

      destructured representation of collection to inflate

    • optionaloptions: Partial<IDeserializeCollectionOptions>

      used to describe format of destructuredSource input

    Returns (P & ICollectionDocument)[]

    an array of documents to attach to collection.data.

deserializeDestructured

  • Database level destructured JSON deserialization routine to minimize memory overhead. Internally, Database supports destructuring via database “serializationMethod’ option and the optional LokiPartitioningAdapter class. It is also available if you wish to do your own structured persistence or data exchange.

    Parameters

    • destructuredSource: string | string[]

      destructured json or array to deserialize from

    • optionaloptions: Partial<IDeserializeDestructuredOptions>

      source format options

    Returns any

    An object representation of the deserialized database, not yet applied to ‘this’ db or document array

dispatchEvent

  • dispatchEvent<T>(event: Event<EventDetail<T>>): boolean

  • Type parameters

    • T: EventName<any, T>

    Parameters

    • event: Event<EventDetail<T>>

    Returns boolean

generateChangesNotification

  • generateChangesNotification(collectionNamesArray?: string[]): ICollectionChange<any>[]

  • (Changes API) : takes all the changes stored in each collection and creates a single array for the entire database. If an array of names of collections is passed then only the included collections will be tracked.

    @see

    private method createChange() in Collection

    Parameters

    • optionalcollectionNamesArray: string[]

      array of collection names. No arg means all collections are processed.

    Returns ICollectionChange<any>[]

    array of changes

getCollection

  • getCollection<U>(collectionName: string): Collection<U>

  • Retrieves reference to a collection by name.

    Type parameters

    • U: object

    Parameters

    • collectionName: string

      name of collection to look up

    Returns Collection<U>

listCollections

  • Returns a list of collections in the database.

    Returns ICollectionSummary[]

    array of objects containing ‘name’, ‘type’, and ‘count’ properties.

loadCollection

  • loadCollection<P>(collection: Collection<P>): void

  • Type parameters

    • P: object

    Parameters

    Returns void

loadDatabase

  • Handles manually loading from file system, local storage, or adapter (such as indexed-db). This method utilizes database configuration options (if provided) to determine which persistence method to use, or environment detection (if configuration was not provided). To avoid contention with any throttledSaves, we will drain the save queue first.

    If you are configured with autosave, you do not need to call this method yourself.

    @example
    db.loadDatabase({}, function(err) {
      if (err) {
        console.log("error : " + err);
      }
      else {
        console.log("database loaded.");
      }
    });

    Parameters

    Returns Promise<any>

loadDatabaseInternal

  • Internal load logic, decoupled from throttling/contention logic

    Parameters

    • optionaloptions: Partial<ILoadJSONOptions<any>>

      not currently used (remove or allow overrides?)

    Returns Promise<any>

loadJSON

  • Inflates a database database from a serialized JSON string

    Type parameters

    • P: object

    Parameters

    • serializedDb: string

      a serialized database database string

    • optionaloptions: Partial<ILoadJSONOptions<P>>

      apply or override collection level settings

    Returns void

loadJSONObject

  • loadJSONObject<P>(databaseObject: unknown, options?: Partial<ILoadJSONOptions<P>>): void

  • Inflates a database database from a JS object

    Type parameters

    • P: object

    Parameters

    • databaseObject: unknown

      a serialized database database string

    • optionaloptions: Partial<ILoadJSONOptions<P>>

      apply or override collection level settings

    Returns void

removeCollection

  • removeCollection(collectionName: string): void

  • Removes a collection from the database.

    Parameters

    • collectionName: string

      name of collection to remove

    Returns void

removeEventListener

  • removeEventListener<T>(type: EventName<T>, callback: Listener<T>, options?: boolean | EventListenerOptions): void

  • Type parameters

    • T: EventName<any, T>

    Parameters

    • type: EventName<T>
    • callback: Listener<T>
    • optionaloptions: boolean | EventListenerOptions

    Returns void

renameCollection

  • renameCollection(oldName: string, newName: string): Collection<object>

  • Renames an existing database collection

    Parameters

    • oldName: string

      name of collection to rename

    • newName: string

      new name of collection

    Returns Collection<object>

saveDatabase

  • saveDatabase(): Promise<boolean>

  • Handles manually saving to file system, local storage, or adapter (such as indexed-db) This method utilizes database configuration options (if provided) to determine which persistence method to use, or environment detection (if configuration was not provided).

    If you are configured with autosave, you do not need to call this method yourself.

    @example
    db.saveDatabase(function(err) {
      if (err) {
        console.log("error : " + err);
      }
      else {
        console.log("database saved.");
      }
    });

    Returns Promise<boolean>

saveDatabaseInternal

  • saveDatabaseInternal(): Promise<void>

  • Internal save logic, decoupled from save throttling logic

    Returns Promise<void>

serialize

  • serialize(options?: { serializationMethod: Normal }): string
  • serialize(options?: { serializationMethod: Pretty }): string
  • serialize(options?: { serializationMethod: Destructured }): string[]

  • Serialize database to a string which can be loaded via loadJSON

    Parameters

    • optionaloptions: { serializationMethod: Normal }

    Returns string

    Stringified representation of the database database.

serializeChanges

  • serializeChanges(collectionNamesArray?: string[]): string

  • (Changes API) - stringify changes for network transmission

    Parameters

    • optionalcollectionNamesArray: string[]

      array of collection names. No arg means all collections are processed.

    Returns string

    string representation of the changes

serializeCollection

  • Collection level utility method to serialize a collection in a ‘destructured’ format

    Parameters

    Returns string | string[]

    A custom, restructured aggregation of independent serializations for a single collection.

serializeDestructured

  • Database level destructured JSON serialization routine to allow alternate serialization methods. Internally, Database supports destructuring via database “serializationMethod’ option and the optional PartitioningAdapter class. It is also available if you wish to do your own structured persistence or data exchange.

    Parameters

    Returns string | string[]

throttledSaveDrain

  • Wait for throttledSaves to complete and invoke your callback when drained or duration is met.

    Parameters

    Returns OpenPromise<boolean> | Promise<boolean>

staticisDatabaseObject

  • isDatabaseObject(x: unknown): x is Database<any>

  • Parameters

    • x: unknown

    Returns x is Database<any>