Initialization

Creating an ODD program

You can use the ODD SDK by creating an ODD program. Here is a minimal example:

const program = await odd.program({
  // `namespace` can also be just a string; it's used as an identifier for caches.
  // If you're developing multiple apps on the same localhost port,
  // make sure these differ.
  namespace: { creator: "Nullsoft", name: "Winamp" }

}).catch(error => {
  switch (error) {
    case odd.ProgramError.InsecureContext:
      // ODD requires HTTPS
      break;
    case odd.ProgramError.UnsupportedBrowser:
      // Browsers must support IndexedDB
      break;
  }

})

Program

An ODD program is a set of components and utilities for building a distributed web application.

export type Program = ShortHands & Events.ListenTo<Events.All<Session>> & {
  auth: AuthenticationStrategy
  capabilities: {
    collect: () => Promise<Maybe<string>> // returns username
    request: (options?: CapabilitiesImpl.RequestOptions) => Promise<void>
    session: (username: string) => Promise<Maybe<Session>>
  }
  configuration: Configuration
  components: Components
  fileSystem: FileSystemShortHands
  session: Maybe<Session>
}

We'll cover each part of a program in upcoming sections. As a quick summary:

• Session. A session including a username and a filesystem instance. A session will be created from an authentication strategy or requested capabilities depending on which approach your application takes.

• Authentication Strategy. A set of functions for registering users and linking devices.

• Capabilities. A set of functions for requesting authorization from another app.

• File System. A set of functions for working with the file system.

• Configuration. The configuration used to instantiate the program.

• Components. Component implementations for authentication strategy, capabilities, crypto, storage, depot, manners, and references.

• Shorthands. Helper functions provided for easy access.

• Event Listeners. Event listeners for file system and session events.

Configuration

You can configure a program with a namespace parameter and a few optional parameters:

export type Configuration = {
  namespace: string | AppInfo
  debug?: boolean
  fileSystem?: {
    loadImmediately?: boolean
    version?: string
  }
  permissions?: Permissions
  userMessages?: UserMessages
}

Namespace

We saw a namespace earlier in our minimal example:

namespace: { creator: "Nullsoft", name: "Winamp" }

A namespace isolates an application in browser storage. This isolation means you can work on multiple apps on localhost at the same port and not worry about them interacting or conflicting. Provide each app a namespace, and they will exist independently.

You can also set the namespace as a string:

namespace: "nullsoft-winamp"

Debug

The debug flag determines whether the ODD SDK should log detailed debugging information to the console. The default value is false.

Filesystem options

The loadImmediately flag determines if the ODD SDK should load the filesystem at initialization. The default value is true.

The filesystem can be loaded after initialization using the program.loadFileSystem shorthand function. In most cases, you will want to load the filesystem immediately, but deferring can sometimes be useful. For example, you can load the filesystem in a Worker after initialization.

The version sets the filesystem version. The version defaults to the latest stable version of WNFS.

Permissions

Permissions are the capabilities to be requested from another application. We'll cover permissions in more detail in the Requesting Capabilities section.

User messages

User messages are alerts that report to the user when the current version of the ODD SDK does not support their filesystem. You can update these messages to provide users with your support information.

Custom Components

You can deeply customize an ODD program by providing component implementations. We'll discuss custom components in the Components section.