jazz signals
A library to help use Jazz with preact signals.
install
npm i -S @nichoth/jazz-signalsdevelop
Start a local vite server
npm startAPI
localAuth
Import a function localAuth that helps with authentication, and has a property createState that returns observable state. This will create and return a signal of a localNode, the object used for persistence/telepathicState.
import { localAuth } from '@nichoth/jazz-signals'localAuth.createState
Create a state object that includes signals.
export interface LocalAuthState {
authStatus:Signal<AuthStatus>;
localNode:Signal<LocalNode|null>;
logoutCount:Signal<number>;
syncAddress?:string;
}
localAuth.createState = function ():LocalAuthStateThe returned state object should be passed into the localAuth function. See an example in the example app.
The signals returned are plain signals; you would want to wrap them in a call to useMemo if you use them in a view component.
function localAuth (
appName:string,
appHostname:string|undefined,
opts:LocalAuthState
):() => voidThis will create a new BrowserLocalAuth, and mutate the signals passed in as opts:LocalAuthState. The return value is a function that will unsubscribe from BrowserLocalAuth. See the example for a demonstration of how the unsubscribe function can be used.
To check if you are logged in, look for the authStatus.value.logout property. If .logout exists, then you are logged in. Call authStatus.value.signUp or authStatus.value.signIn to handle creating an account and logging in, respectively. See an example of handling auth.
telepathicSignal
function telepathicSignal<T extends CoValueImpl> ({
id,
localNode
}:{
id?:CoID<T>,
localNode:Signal<LocalNode|null>
}):Signal<[ T|null, (()=>void)|null ]> {example
localAuth
An example of an application that consumes this package is in the example directory.
Create a localNode by mutating the signals that are passed in. Signals are created by localNode.createState.
You should create a state object first with localAuth.createState, then pass the state to localAuth.
import { localAuth } from '@nichoth/jazz-signals'
import { useEffect, useMemo } from 'preact/hooks'
function MyComponent ({ appHostName, syncAddress, appName }) {
const state = useMemo(() => localAuth.createState(), [])
const { localNode } = state // <-- a signal for our localNode
/**
* Handle auth, create a node
*/
useEffect(() => {
let unlisten:()=>void = () => null
localAuth(appName, appHostName, { ...state }).then(_unlisten => {
unlisten = _unlisten
})
return unlisten
}, [appName, appHostName, syncAddress, logoutCount.value])
}telepathicSignal
Create a new signal that is subscribed to any changes from the cojson
object referenced by the given id.
import { telepathicSignal } from '@nichoth/jazz-signals'
const mySignal = telepathicSignal({
id: 'co_zPLDBXZD5UuZtYGzpqAvgAAHhs4',
localNode
})import { telepathicSignal } from '@nichoth/jazz-signals'
import { useMemo } from 'preact/hooks'
function Component () {
const projectSignal = useMemo(() => {
return telepathicSignal({
// get the `id` from the URL or something
id: 'co_zPLDBXZD5UuZtYGzpqAvgAAHhs4',
localNode // <-- here we consume the localNode we created earlier
})
}, [params.id, localNode.value])
const [project] = projectSignal.value
// get tasks (the list of things to do)
// this is where we subscribe to task changes
const tasksSignal = useMemo(() => {
if (!project) return signal([])
// we depend on the 'tasks' key existing.
const tasksId = project.get('tasks')
return telepathicSignal({ id: tasksId, localNode })
}, [project, localNode.value])
const [tasks] = tasksSignal.value
return (<div>
<h2>{project.get('title')}</h2>
<ul className="todo-list">
{tasks?.map((taskId: CoID<Task>) => {
// subscribe to each TODO list item
const [task] = useMemo(
() => telepathicSignal<Task>({ id: taskId, localNode }),
[taskId, localNode.value]
).value
// The view will re-render when the task updates.
// This is magically in sync with multiple devices.
// You can create an invitation for a second device, and changes
// will automatically be visible in both places.
return (<li key={taskId}>
{task?.get('done') ?
(<s>{task.get('text')}</s>) :
(<span>{task.get('text')}</span>)
}
</li>)
})}
</ul>
</div>)
}