@jamsocket/javascript

@jamsocket/javascript

@jamsocket/javascript provides Javascript/Typescript and React libraries for interacting with session backends and the Jamsocket Platform.

The @jamsocket/javascript library is composed of

• /server provides functions for spawning session backends securely
• /client is a Javascript/Typescript library for a interacting with session backends
• /react uses the client library to give you the same functionality in simple React hooks
• /socketio lets you connect to a socketio server in your session backend with React hooks

View the open source library on Github.

Installation

npm install @jamsocket/javascript

Example

Here's an example of how different parts of the @jamsocket/javscript library work together.

import Jamsocket from '@jamsocket/javascript/server'

const jamsocket = Jamsocket.init({
   account: '[YOUR ACCOUNT]',
   token: '[YOUR TOKEN]',
   service: '[YOUR SERVICE]',
   // during develpment, you can simply pass { dev: true }
})

const spawnResult = await jamsocket.spawn()

import { SessionBackendProvider, useReady } from '@jamsocket/javascript/react'
import { SocketIOProvider, useEventListener, useSend } from '@jamsocket/javascript/socketio'
import type { SpawnResult } from '@jamsocket/javascript/types'

function Root() {
  return(
    <SessionBackendProvider spawnResult={spawnResult}>
      <SocketIOProvider url={spawnResult.url}>
        <MyComponent />
      </SocketIOProvider>
    </SessionBackendProvider>
  )
}

function MyComponent() {
  const ready = useReady()
  const sendEvent = useSend()

  useEffect(() => {
    if (ready) {
      sendEvent('some-event', someValue)
    }
  }, [ready])

  useEventListener('another-event', (args) => {
    // do something when receiving an event message from your session backend...
  })
  //...
}

Library Reference

@jamsocket/javascript/server

init()

Create a Jamsocket instance using the init function from @jamsocket/javascript/server folder. The returned Jamsocket instance has a spawn function that you can use to spawn a session backend.

Backends should only be spawned server-side, since the Jamsocket Auth Token must be kept secret.

Usage

In local development, you can simply set dev to true.

import Jamsocket from '@jamsocket/javascript/server'

const jamsocket = Jamsocket.init({ dev: true })

const spawnResult = await jamsocket.spawn()

In production, provide your account, token, and service information.

import Jamsocket from '@jamsocket/javascript/server'

const jamsocket = Jamsocket.init({
  account: '[YOUR ACCOUNT]',
  token: '[YOUR TOKEN]',
  service: '[YOUR SERVICE]',
})

const spawnResult = await jamsocket.spawn({
  lock: 'my-lock',
  env: { MY_ENV_VAR: 'foo' },
  gracePeriodSeconds: 300,
})

const spawnResult = await jamsocket.spawn()

Typescript

export type JamsocketDevInitOptions = {
  dev: true
  port?: number
}

export type JamsocketInitOptions =
  | {
      account: string
      token: string
      service: string
    }
  | JamsocketDevInitOptions

export type JamsocketSpawnOptions = {
  lock?: string
  env?: Record<string, string>
  gracePeriodSeconds?: number
}

@jamsocket/javascript/client

SessionBackend

import { SessionBackend } from '@jamsocket/javascript/client'

const sessionBackend = new SessionBackend(spawnResultUrl, statusUrl)

isReady()

isReady returns a boolean value that is true if the backend is ready.

isReady()

import { SessionBackend } from '@jamsocket/javascript/client'

const sessionBackend = new SessionBackend(spawnResultUrl, statusUrl)

const isReady = sessionBackend.isReady()

onReady()

onReady takes a callback function that is called when the session backend is ready.

import { SessionBackend } from '@jamsocket/javascript/client'

const sessionBackend = new SessionBackend(spawnResultUrl, statusUrl)

sessionBackend.onReady(() => {
    // your logic here
})

destroy()

destroy terminates your client connection, but it does not terminate the session backend.

import { SessionBackend } from '@jamsocket/javascript/client'

const sessionBackend = new SessionBackend(spawnResultUrl, statusUrl)

sessionBackend.destroy()

@jamsocket/javascript/react

SessionBackendProvider

Wrap the root of your project with the SessionBackendProvider so that the children components can utilize the React hooks.

The SessionBackendProvider must be used in conjunction with @jamsocket/javascript/server in order to access the spawn result returned by the spawn function.

import { SessionBackendProvider } from '@jamsocket/javascript/react'
import type { SpawnResult } from '@jamsocket/javascript/types'

export default function HomeContainer({ spawnResult }: { spawnResult: SpawnResult }) {
  return (
    <SessionBackendProvider spawnResult={spawnResult}>
        <Home />
    </SessionBackendProvider>
  )
}

useReady

Is a React hook that returns a boolean that is true if the session backend is ready.

import { useReady } from '@jamsocket/javascript/react'

const isReady = useReady()

@jamsocket/javascript/socketio

SocketIOProvider

The SocketIOProvider uses the url returned from the spawn function to connect to a SocketIO server running in your session backend.

Using the SocketIOProvider lets you use the React hooks in @jamsocket/javascript/socketio. It must be used in conjunction with @jamsocket/javascript/server and @jamsocket/javascript/react in order to properly access the session backend.

The SocketIOProvider must be a child of the SessionBackendProvider because it depends on the SessionBackendProvider's context.

import { SessionBackendProvider } from '@jamsocket/javascript/react'
import { SocketIOProvider } from '@jamsocket/javascript/socketio'
import type { SpawnResult } from '@jamsocket/javascript/types'

export default function HomeContainer({ spawnResult }: { spawnResult: SpawnResult }) {
  return (
    <SessionBackendProvider spawnResult={spawnResult}>
      <SocketIOProvider url={spawnResult.url}>
          <Home />
      </SocketIOProvider>
    </SessionBackendProvider>
  )
}

useSend

useSend lets you send events to the SocketIO server.

import { sendEvent } from '@jamsocket/javascript/socketio'

const sendEvent = useSend()

sendEvent('new-event', eventMessage)

useEventListener

useEventListener lets you listen to events coming from the SocketIO server.

import { useEventListener } from '@jamsocket/javascript/socketio'

useEventListener<T>('event', (data: T) => {
    // do something when a new event appears
})