Skip to content

Instance.md

Latest commit

 

History

History
262 lines (168 loc) · 8.31 KB

Instance.md

File metadata and controls

262 lines (168 loc) · 8.31 KB

🔐 Constructor: new TinyOlm.Instance(userId, deviceId, password?)

Creates a new TinyOlmInstance instance bound to a specific user and device.

🧰 Parameters

Name Type Description
userId string The user ID to associate with this account and its cryptographic sessions.
deviceId string The device ID representing this instance of the user.
password string (Optional) A password linked to this account and its sessions.

📦 Properties

Property Type Description
this.userId string The user's unique identifier.
this.deviceId string The identifier for this specific device.
this.password string Password used in this session (optional).
this.account Olm.Account | null The associated Olm account (or null if unset).
this.sessions Map<string, Olm.Session> Direct peer-to-peer sessions by user/device.
this.groupSessions Map<string, Olm.OutboundGroupSession> Group encryption sessions (outbound).
this.groupInboundSessions Map<string, Olm.InboundGroupSession> Group decryption sessions (inbound).

🛠️ init()

Initializes the Olm library and creates a new account.

🔁 Returns

  • Promise: Resolves when the Olm library is initialized and the account is created.

🧑‍💻 Example

await tinyOlmInstance.init();
console.log('Olm library initialized and account created.');

🏗️ initIndexedDb(dbName?)

Initializes the IndexedDB database for this TinyOlmInstance and attempts to restore all saved cryptographic state (account, sessions, group sessions).

📥 Parameters

Name Type Default Description
dbName string 'TinyOlmInstance' (Optional) The name of the database.

🔁 Returns

  • Promise<IDBDatabase>: Resolves once the database is fully initialized and restored.

⚠️ Throws

  • Error:
    • If not running in a browser.
    • If dbName is not a string.
    • If the database has already been initialized.

🧠 What it does

  1. Ensures the environment is a browser and that Olm is loaded.
  2. Opens or upgrades the IndexedDB database with object stores:
    • account
    • sessions
    • groupSessions
    • groupInboundSessions
  3. Emits internal setup events for password, userId, and deviceId.
  4. Loads and restores:
    • Your account from storage.
    • All direct sessions.
    • All group sessions (outbound and inbound).
  5. Starts watching for any future pickle updates.

🌐 validateIsBrowser()

Checks whether the current environment supports IndexedDB — meaning it's running in a web browser.

⚠️ Throws

  • Error: If not running in a browser or if indexedDB is unavailable.

🧠 Purpose

This method ensures that the TinyOlm instance is being used in an environment compatible with browser-based storage.

🗃️ getDbName()

Returns the name of the IndexedDB database used by the TinyOlmInstance.

🔁 Returns

  • string: The name of the current IndexedDB database.

⚠️ Throws

  • Error: If the internal database name (#dbName) is not set correctly (i.e., not a string).

🧠 Note

This method relies on an internal private field #dbName and is used to access the database identifier safely.

🛠️ getDb()

Returns the active IndexedDB database instance currently used by TinyOlmInstance.

🔁 Returns

  • IDBDatabase: The open and initialized IndexedDB database instance.

⚠️ Throws

  • Error: If the database hasn't been initialized yet.
    (Hint: Make sure to call initIndexedDb() before using this method.)

🧠 Note

This method accesses the internal private field #db and ensures that the database is ready before continuing.

🧪 _testIndexedDb()

(Internal method)
Used for debugging purposes: logs all entries currently stored in the database's object stores.

🔁 Returns

  • Promise<void> — Logs the contents of:
    • account
    • sessions
    • groupSessions
    • groupInboundSessions

🗂️ exportInstance(password = this.password)

Exports the entire TinyOlmInstance as a serial structure.

📥 Parameters

Name Type Description
password string The password used to pickle the instance. Default is the current instance password.

🔁 Returns

  • ExportedOlmInstance: A serial structure containing the pickled account, sessions, group sessions, and inbound group sessions.

🧠 What it does

  • Exports the full instance, including account, sessions, group sessions, and inbound group sessions, all pickled with the specified password.

🧑‍💻 Example

const exportedInstance = tinyOlmInstance.exportInstance('mySecurePassword');

📦 importInstance(data, password?)

Restores a full exported TinyOlmInstance, including account, sessions, and group sessions.

🔁 Returns

  • Promise

🧼 Behavior

  • Restores the account via importAccount().
  • Iterates over data.sessions, calling importSession() on each.
  • Iterates over data.groupSessions, calling importGroupSession() on each.
  • Iterates over data.groupInboundSessions, calling importInboundGroupSession() on each.

📌 Note

This is the high-level method used to restore the entire cryptographic state, e.g., after logging in from another device.

🧑‍💻 Example

await tinyOlmInstance.importInstance(exportedData, 'secure-password');

🧹 dispose()

Disposes the TinyOlmInstance by clearing all Olm sessions (both individual and group) and releasing the account from memory.

🔁 Returns

  • Promise

🧼 Behavior

  • Clears all 1:1 Olm sessions via clearSessions().
  • Frees and nullifies the Olm account, emitting TinyOlmEvents.ResetAccount.
  • Clears all outbound group sessions.
  • Clears all inbound group sessions.

📌 Note

This should be called when the instance is no longer needed, to ensure that memory is properly released and cryptographic material is not kept in memory unnecessarily.

🧑‍💻 Example

await tinyOlmInstance.dispose();

🗄️ existsDb()

Checks whether the internal IndexedDB instance has been initialized and is currently available.

🔁 Returns

  • boolean: true if the database instance exists and is ready for use, otherwise false.

🧼 Behavior

  • Verifies if the private #db property has been set (i.e., the database has been opened).
  • Returns true if an active IDBDatabase instance is present.

📌 Note

This is a lightweight check that does not open or interact with the database—only verifies internal state.

🧑‍💻 Example

if (tinyOlmInstance.existsDb()) {
  console.log('Database is ready!');
} else {
  console.warn('Database is not initialized.');
}

🧵 getQueue()

Returns the internal TinyPromiseQueue (from tiny-essentials module) used to manage asynchronous task queuing and execution order.

This queue ensures that encryption and decryption operations — or any session-related activities — are executed sequentially, avoiding race conditions.

Returns:

  • TinyPromiseQueue: A queue manager instance that controls promise execution order.

🧑‍💻 Example:

const queue = tinyOlm.getQueue();
queue.enqueue(() => someAsyncTask());
queue.enqueuePoint(() => someAsyncTask());