modules/scheduling-queues/hyper-p2p-cron-gossip/docs/api.md

API: hyper-p2p-cron-gossip

Protocol: cron-gossip/v1

Export: { HyperP2PCronGossip, PROTOCOL }

Overview

HyperP2PCronGossip stores jobs in a local Map keyed by jobId. schedule(expr, jobId) registers an expression. tick(now) evaluates due jobs, emits fire, and gossips cron-fire to peers. Remote fires update lastRun and emit remote-fire. Expressions support @every Nms|s|m|h or five-field UTC cron (minute hour day month weekday).

Constructor

Option	Type	Default	Description
topic	string | Buffer | null	null	Hyperswarm topic
keyPair	KeyPair	hypercore-crypto.keyPair()	Swarm identity; peerHex derived for gossip

Methods

schedule(expr, jobId)

• Returns: { jobId, expr, lastRun, at } job record
• Throws: ValidationError if jobId or expr empty
• Emits: schedule

unschedule(jobId)

• Returns: boolean — whether job existed

tick(now = Date.now())

Evaluates all jobs; fires due ones.

• Returns: string[] — fired jobId list
• Emits: fire per local job

list() / get(jobId)

Snapshots of registered jobs.

async ready() / async close()

close() clears jobs, destroys swarm, emits closed.

getStats()

Field	Type	Description
scheduled	number	schedule calls
fired	number	Local tick fires
gossipIn / gossipOut	number	Wire counters
jobs	number	Map size
protocol	string	cron-gossip/v1

Events

Event	Payload	When
schedule	job object	schedule()
fire	{ jobId, at }	Local tick fired job
remote-fire	{ jobId, peer, at }	Inbound cron-fire
closed	—	close()

getStats()

Shallow copy with live jobs count.

Wire

type	fields	direction	behavior
cron-fire	jobId, expr, peer, at	bidirectional	Update/create job lastRun; emit remote-fire

Gossip only sends when _peerMsgs is populated (after ready() + connections).

Cron expression helpers

Form	Example	Semantics
@every	@every 30s	Interval since lastRun
Five-field	0 * * * *	UTC minute/hour/day/month/weekday match

Errors

Message	Source
jobId is required / expr is required	schedule
topic is required for createSwarm	swarm

Testing

cd modules/scheduling-queues/hyper-p2p-cron-gossip
npm install && npm test
bare examples/basic.js

Drive tick with injected now for deterministic tests.