Documentation
¶
Overview ¶
Package scheduler implements a scheduled function execution plugin for Base.
It provides deferred and time-based function execution with exactly-once semantics, retry support, and post-commit scheduling (functions scheduled inside hooks run only after the hook's DB transaction commits).
The scheduler uses an internal Base collection "_scheduled_functions" with fields:
- functionName (text, required)
- args (json)
- scheduledAt (date, required)
- status (select: pending, running, completed, failed, cancelled)
- result (json)
- error (text)
- retryCount (number)
- createdAt (autodate)
- completedAt (date)
Example:
scheduler.MustRegister(app, scheduler.Config{
PollInterval: 1 * time.Second,
MaxConcurrent: 10,
RetryCount: 3,
RetryDelay: 5 * time.Second,
})
Index ¶
- Constants
- func CancelScheduled(app core.App, id string) error
- func ListScheduled(app core.App, status string) ([]*core.Record, error)
- func MustRegister(app core.App, config Config)
- func Register(app core.App, config Config) error
- func RegisterJSVM(app core.App, vm *goja.Runtime)
- func ScheduleAfter(app core.App, delayMs int64, functionName string, args any) (string, error)
- func ScheduleAt(app core.App, at time.Time, functionName string, args any) (string, error)
- type Config
- type ExecuteFunc
Constants ¶
const ( // CollectionName is the internal collection used to persist scheduled functions. CollectionName = "_scheduled_functions" StatusPending = "pending" StatusRunning = "running" StatusCompleted = "completed" StatusFailed = "failed" StatusCancelled = "cancelled" )
Variables ¶
This section is empty.
Functions ¶
func CancelScheduled ¶
CancelScheduled cancels a pending scheduled function by ID. Returns an error if the function is not found or is not in pending status.
func ListScheduled ¶
ListScheduled returns all scheduled function records matching the optional status filter. If status is empty, all records are returned.
func MustRegister ¶
MustRegister registers the scheduler plugin in the provided app instance and panics if it fails.
Example:
scheduler.MustRegister(app, scheduler.Config{
PollInterval: 1 * time.Second,
MaxConcurrent: 10,
RetryCount: 3,
RetryDelay: 5 * time.Second,
})
func RegisterJSVM ¶
RegisterJSVM registers the scheduler JS bindings into a goja runtime.
This adds the following global functions:
- scheduleAfter(delayMs, functionName, args?) - schedule execution after a delay
- scheduleAt(isoDateString, functionName, args?) - schedule execution at a specific time
- cancelScheduled(scheduledId) - cancel a pending scheduled function
- listScheduled(status?) - list scheduled functions, optionally filtered by status
Example JS usage:
onRecordAfterCreateSuccess((e) => {
scheduleAfter(0, "sendNotification", { recordId: e.record.id })
}, "tasks")
cronAdd("cleanup", "0 3 * * *", () => {
scheduleAfter(0, "cleanupExpired", {})
})
// Schedule something 30 minutes from now
scheduleAfter(1800000, "generateReport", { type: "daily" })
// Schedule at a specific time
scheduleAt("2026-03-01T09:00:00Z", "sendReminder", { userId: "abc123" })
// Cancel a scheduled function
cancelScheduled("scheduled_record_id")
// List all pending scheduled functions
const pending = listScheduled("pending")
func ScheduleAfter ¶
ScheduleAfter creates a new scheduled function to execute after delayMs milliseconds.
If the calling context is inside a transaction, the record is inserted but the function won't be picked up until after the transaction commits (the record becomes visible to the poller only after commit).
Returns the scheduled function record ID.
Types ¶
type Config ¶
type Config struct {
// OnExecute is called to execute a scheduled function.
// If nil, scheduled functions will fail with "no executor configured".
OnExecute ExecuteFunc
// PollInterval controls how frequently the scheduler checks for due functions.
// Defaults to 1 second.
PollInterval time.Duration
// RetryDelay is the base delay between retries of a failed function.
// Defaults to 5 seconds.
RetryDelay time.Duration
// MaxConcurrent limits the number of concurrently executing scheduled functions.
// Defaults to 10.
MaxConcurrent int
// RetryCount is the maximum number of retry attempts for a failed function.
// Defaults to 3.
RetryCount int
}
Config defines the configuration for the scheduler plugin.
Source Files