Class ShogunCore

Main ShogunCore class - implements the IShogunCore interface

This is the primary entry point for the Shogun SDK, providing access to:

  • Decentralized database (GunDB)
  • Authentication methods (traditional, WebAuthn, MetaMask)
  • Plugin system for extensibility
  • DID (Decentralized Identity) management
  • RxJS integration for reactive programming

Since

2.0.0

Implements

Constructors

constructor

Properties

config eventEmitter gun gundb plugins provider? rx storage user API_VERSION

Methods

compute configureLogging createUserWithGunDB emit ensureUserHasDID get getAuthenticationMethod getPlugin getPluginsByCategory getRecentErrors getRpcUrl hasPlugin isLoggedIn login logout match observe observeUser off on once onceObservable put register registerBuiltinPlugins removeAllListeners rxPut rxSet rxUserPut setRpcUrl signUp unregister userGet userPut

Constructors

constructor

  • new ShogunCore(config: ShogunSDKConfig): ShogunCore

    Initialize the Shogun SDK

    Parameters

    Returns ShogunCore

    Description

    Creates a new instance of ShogunCore with the provided configuration. Initializes all required components including storage, event emitter, GunDB connection, and plugin system.

Properties

config

config: ShogunSDKConfig

SDK configuration

Private ReadonlyeventEmitter

eventEmitter: EventEmitter

Event emitter for SDK events

gun

gun: IGunInstance<any>

Gun database instance

gundb

gundb: GunDB

GunDB wrapper

Private Readonlyplugins

plugins: Map<string, ShogunPlugin> = ...

Plugin registry

Optionalprovider

provider?: Provider

Ethereum provider

rx

rx: GunRxJS

RxJS integration

storage

storage: ShogunStorage

Storage implementation

user

user: null | IGunUserInstance<any, any, any, any>

Gun user instance

Static ReadonlyAPI_VERSION

API_VERSION: "2.0.0"

Current API version - used for deprecation warnings and migration guidance

Methods

compute

  • compute<T, R>(
        sources: (string | Observable<any>)[],
        computeFn: (...values: T[]) => R,
    ): Observable<R>

    Compute derived values from gun data

    Type Parameters

    • T
    • R

    Parameters

    • sources: (string | Observable<any>)[]

      Array of paths or observables to compute from

    • computeFn: (...values: T[]) => R

      Function that computes a new value from the sources

    Returns Observable<R>

    Observable of computed values

configureLogging

  • configureLogging(config: LoggingConfig): void

    Configure logging behavior for the Shogun SDK

    Parameters

    • config: LoggingConfig

      Logging configuration object containing:

      • level: The minimum log level to display (error, warn, info, debug, trace)
      • logToConsole: Whether to output logs to the console (default: true)
      • customLogger: Optional custom logger implementation
      • logTimestamps: Whether to include timestamps in logs (default: true)

    Returns void

    Description

    Updates the logging configuration for the SDK. Changes take effect immediately for all subsequent log operations.

PrivatecreateUserWithGunDB

  • createUserWithGunDB(
        username: string,
        password: string,
    ): Promise<{ error?: string; success: boolean; userPub?: string }>

    Create a new user with GunDB

    Parameters

    • username: string

      Username

    • password: string

      Password

    Returns Promise<{ error?: string; success: boolean; userPub?: string }>

    Promise with success status and user public key

    Description

    Creates a new user in GunDB with error handling

emit

  • emit(eventName: string | symbol, data?: any): boolean

    Emits an event through the core's event emitter. Plugins should use this method to emit events instead of accessing the private eventEmitter directly.

    Parameters

    • eventName: string | symbol

      The name of the event to emit.

    • Optionaldata: any

      The data to pass with the event.

    Returns boolean

PrivateensureUserHasDID

  • ensureUserHasDID(options?: DIDCreateOptions): Promise<null | string>
    Private

    Ensure the current user has a DID associated, creating one if needed

    Parameters

    • Optionaloptions: DIDCreateOptions

      Optional configuration for DID creation including:

      • network: The network to use (default: 'main')
      • controller: The controller of the DID (default: user's public key)
      • services: Array of service definitions to add to the DID document

    Returns Promise<null | string>

    The DID identifier string or null if operation fails

    Description

    Checks if the authenticated user already has a DID. If not, creates a new one. If the user already has a DID and options are provided, updates the DID document accordingly.

get

  • get(path: string): Promise<any>

    Retrieves data from a Gun node at the specified path

    Parameters

    • path: string

      The path to the Gun node

    Returns Promise<any>

    Promise that resolves with the node data or rejects with an error

getAuthenticationMethod

  • getAuthenticationMethod(type: "webauthn" | "password" | "metamask"): unknown

    Get an authentication method plugin by type

    Parameters

    • type: "webauthn" | "password" | "metamask"

      The type of authentication method

    Returns unknown

    The authentication plugin or undefined if not available This is a more modern approach to accessing authentication methods

getPlugin

  • getPlugin<T>(name: string): undefined | T

    Retrieve a registered plugin by name

    Type Parameters

    • T

      Type of the plugin or its public interface

    Parameters

    • name: string

      Name of the plugin

    Returns undefined | T

    The requested plugin or undefined if not found

getPluginsByCategory

getRecentErrors

  • getRecentErrors(count?: number): ShogunError[]

    Retrieve recent errors logged by the system

    Parameters

    • count: number = 10

      Number of errors to retrieve (default: 10)

    Returns ShogunError[]

    List of most recent errors

getRpcUrl

  • getRpcUrl(): null | string

    Get the currently configured RPC URL

    Returns null | string

    The current provider URL or null if not set

hasPlugin

  • hasPlugin(name: string): boolean

    Check if a plugin is registered

    Parameters

    • name: string

      Name of the plugin to check

    Returns boolean

    true if the plugin is registered, false otherwise

isLoggedIn

  • isLoggedIn(): boolean

    Check if user is logged in

    Returns boolean

    True if user is logged in, false otherwise

    Description

    Verifies authentication status by checking GunDB login state and presence of authentication credentials in storage

login

  • login(username: string, password: string): Promise<AuthResult>

    Authenticate user with username and password

    Parameters

    • username: string

      Username

    • password: string

      User password

    Returns Promise<AuthResult>

    Promise with authentication result

    Description

    Attempts to log in user with provided credentials. Emits login event on success.

logout

  • logout(): void

    Perform user logout

    Returns void

    Description

    Logs out the current user from GunDB and emits logout event. If user is not authenticated, the logout operation is ignored.

match

  • match<T>(path: any, matchFn?: (data: any) => boolean): Observable<T[]>

    Match data based on Gun's '.map()' and convert to Observable

    Type Parameters

    • T

    Parameters

    • path: any

      Path to the collection

    • OptionalmatchFn: (data: any) => boolean

      Optional function to filter results

    Returns Observable<T[]>

    Observable array of matched items

observe

  • observe<T>(path: string): Observable<T>

    Observe a Gun node for changes

    Type Parameters

    • T

    Parameters

    • path: string

      Path to observe (can be a string or a Gun chain)

    Returns Observable<T>

    Observable that emits whenever the node changes

observeUser

  • observeUser<T>(path: string): Observable<T>

    Observe user data

    Type Parameters

    • T

    Parameters

    • path: string

      Path to observe in user space

    Returns Observable<T>

    Observable that emits whenever the user data changes

off

  • off(eventName: string | symbol, listener: (data: unknown) => void): this

    Remove an event listener

    Parameters

    • eventName: string | symbol

      The name of the event to stop listening for

    • listener: (data: unknown) => void

      The callback function to remove

    Returns this

on

  • on(eventName: string | symbol, listener: (data: unknown) => void): this

    Add an event listener

    Parameters

    • eventName: string | symbol

      The name of the event to listen for

    • listener: (data: unknown) => void

      The callback function to execute when the event is emitted

    Returns this

once

  • once(eventName: string | symbol, listener: (data: unknown) => void): this

    Add a one-time event listener

    Parameters

    • eventName: string | symbol

      The name of the event to listen for

    • listener: (data: unknown) => void

      The callback function to execute when the event is emitted

    Returns this

onceObservable

  • onceObservable<T>(path: any): Observable<T>

    Get data once and return as Observable

    Type Parameters

    • T

    Parameters

    • path: any

      Path to get data from

    Returns Observable<T>

    Observable that emits the data once

put

  • put(data: Record<string, any>): Promise<any>

    Stores data in Gun at the root level

    Parameters

    • data: Record<string, any>

      The data to store

    Returns Promise<any>

    Promise that resolves when data is stored or rejects with an error

register

  • register(plugin: ShogunPlugin): void

    Register a new plugin with the SDK

    Parameters

    Returns void

    Throws

    Error if a plugin with the same name is already registered

PrivateregisterBuiltinPlugins

  • registerBuiltinPlugins(config: ShogunSDKConfig): void
    Private

    Register built-in plugins based on configuration

    Parameters

    Returns void

removeAllListeners

  • removeAllListeners(eventName?: string | symbol): this

    Remove all listeners for a specific event or all events

    Parameters

    • OptionaleventName: string | symbol

      Optional. The name of the event to remove listeners for. If not provided, all listeners for all events are removed.

    Returns this

rxPut

  • rxPut<T>(path: any, data: T): Observable<T>

    Put data and return an Observable

    Type Parameters

    • T

    Parameters

    • path: any

      Path where to put the data

    • data: T

      Data to put

    Returns Observable<T>

    Observable that completes when the put is acknowledged

rxSet

  • rxSet<T>(path: any, data: T): Observable<T>

    Set data on a node and return an Observable

    Type Parameters

    • T

    Parameters

    • path: any

      Path to the collection

    • data: T

      Data to set

    Returns Observable<T>

    Observable that completes when the set is acknowledged

rxUserPut

  • rxUserPut<T>(path: string, data: T): Observable<T>

    User put data and return an Observable (for authenticated users)

    Type Parameters

    • T

    Parameters

    • path: string

      Path where to put the data

    • data: T

      Data to put

    Returns Observable<T>

    Observable that completes when the put is acknowledged

setRpcUrl

  • setRpcUrl(rpcUrl: string): boolean

    Set the RPC URL used for Ethereum network connections

    Parameters

    • rpcUrl: string

      The RPC provider URL to use

    Returns boolean

    True if the URL was successfully set

signUp

  • signUp(
        username: string,
        password: string,
        passwordConfirmation?: string,
    ): Promise<SignUpResult>

    Register a new user with provided credentials

    Parameters

    • username: string

      Username

    • password: string

      Password

    • OptionalpasswordConfirmation: string

      Password confirmation

    Returns Promise<SignUpResult>

    Registration result

    Description

    Creates a new user account with the provided credentials. Validates password requirements and emits signup event on success.

unregister

  • unregister(pluginName: string): void

    Unregister a plugin from the SDK

    Parameters

    • pluginName: string

      Name of the plugin to unregister

    Returns void

userGet

  • userGet(path: string): Promise<any>

    Retrieves data from the authenticated user's space at the specified path

    Parameters

    • path: string

      The path to the user data

    Returns Promise<any>

    Promise that resolves with the user data or rejects with an error

userPut

  • userPut(data: Record<string, any>): Promise<any>

    Stores data in the authenticated user's space

    Parameters

    • data: Record<string, any>

      The data to store in user space

    Returns Promise<any>

    Promise that resolves when data is stored or rejects with an error

Settings

Member Visibility

On This Page

Constructors
Properties
Methods