velocious-jobler 0.0.2

package/src/backend/jobler-job-runner.js

@@ -0,0 +1,100 @@
+// @ts-check
+
+export const JOBLER_JOB_STATUS_PENDING = "pending"
+export const JOBLER_JOB_STATUS_RUNNING = "running"
+export const JOBLER_JOB_STATUS_SUCCEEDED = "succeeded"
+export const JOBLER_JOB_STATUS_FAILED = "failed"
+
+/**
+ * The subset of a jobler-job model this runner needs. Any Velocious model with a
+ * `status` / `progress_current` / `progress_total` / `status_message` /
+ * `error_message` / `started_at` / `finished_at` schema satisfies it.
+ * @typedef {object} JoblerJobLike
+ * @property {(status: string) => void} setStatus
+ * @property {(current: number) => void} setProgressCurrent
+ * @property {(total: number | null) => void} setProgressTotal
+ * @property {(message: string | null) => void} setStatusMessage
+ * @property {(message: string | null) => void} setErrorMessage
+ * @property {(at: Date) => void} setStartedAt
+ * @property {(at: Date) => void} setFinishedAt
+ * @property {() => Promise<unknown>} save
+ */
+
+/**
+ * @typedef {object} JoblerProgressReporter
+ * @property {(args: {current?: number, total?: number | null, message?: string | null}) => Promise<void>} progress
+ * @property {(message: string) => Promise<void>} message
+ */
+
+/**
+ * Runs a unit of work while keeping a jobler-job's status and progress live. Each
+ * update is a `save()`, which — because the job is a broadcasting Velocious
+ * frontend-model resource — pushes a websocket update the UI can render as it
+ * happens. Framework-agnostic: pass any model that implements {@link JoblerJobLike}
+ * and, optionally, an `onError` reporter (e.g. your app's bug reporter).
+ */
+export default class JoblerJobRunner {
+  /**
+   * @param {{onError?: (error: Error, joblerJob: JoblerJobLike) => (void | Promise<void>)}} [args={}]
+   */
+  constructor(args = {}) {
+    this.onError = args.onError
+  }
+
+  /**
+   * Marks the job running, runs `work` (handed a progress reporter), then marks it
+   * succeeded. On failure it marks the job failed, calls `onError` if provided, and
+   * rethrows so the dispatching background job's retry policy still applies.
+   * @param {{joblerJob: JoblerJobLike, work: (report: JoblerProgressReporter) => Promise<void>}} args
+   * @returns {Promise<void>}
+   */
+  async run({joblerJob, work}) {
+    /** @type {JoblerProgressReporter} */
+    const report = {
+      progress: async ({current, total, message} = {}) => {
+        if (current !== undefined) {
+          joblerJob.setProgressCurrent(current)
+        }
+
+        if (total !== undefined) {
+          joblerJob.setProgressTotal(total)
+        }
+
+        if (message !== undefined) {
+          joblerJob.setStatusMessage(message)
+        }
+
+        await joblerJob.save()
+      },
+      message: async (message) => {
+        joblerJob.setStatusMessage(message)
+        await joblerJob.save()
+      }
+    }
+
+    joblerJob.setStatus(JOBLER_JOB_STATUS_RUNNING)
+    joblerJob.setStartedAt(new Date())
+    await joblerJob.save()
+
+    try {
+      await work(report)
+
+      joblerJob.setStatus(JOBLER_JOB_STATUS_SUCCEEDED)
+      joblerJob.setFinishedAt(new Date())
+      await joblerJob.save()
+    } catch (error) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+
+      joblerJob.setStatus(JOBLER_JOB_STATUS_FAILED)
+      joblerJob.setErrorMessage(normalizedError.message)
+      joblerJob.setFinishedAt(new Date())
+      await joblerJob.save()
+
+      if (this.onError) {
+        await this.onError(normalizedError, joblerJob)
+      }
+
+      throw normalizedError
+    }
+  }
+}

package/src/database/migrations/20260630140000-create-jobler-jobs.js

@@ -0,0 +1,36 @@
+// @ts-check
+
+import Migration from "velocious/build/src/database/migration/index.js"
+
+/**
+ * Generic background-job progress records (a jobler-style tracker). A service
+ * creates one before starting heavy async work and updates its status/progress as
+ * it runs; the Expo UI subscribes to the broadcasting frontend model to show live
+ * progress. Lives in the global/default DB only — never a project tenant DB, since
+ * a job tracking a tenant-DB teardown cannot live inside the database it drops.
+ */
+export default class CreateJoblerJobs extends Migration {
+  /** @returns {Promise<void>} */
+  async up() {
+    await this.createTable("jobler_jobs", (table) => {
+      table.string("name", {null: false})
+      table.string("kind", {maxLength: 64, null: false})
+      table.string("status", {default: "pending", maxLength: 32, null: false})
+      table.integer("progress_current", {default: 0, null: false})
+      table.integer("progress_total", {null: true})
+      table.string("status_message", {null: true})
+      table.text("error_message", {null: true})
+      table.text("result_data", {null: true})
+      table.datetime("started_at", {null: true})
+      table.datetime("finished_at", {null: true})
+      table.timestamps()
+    })
+    await this.addIndex("jobler_jobs", ["kind", "status"], {name: "index_jobler_jobs_on_kind_and_status"})
+    await this.addIndex("jobler_jobs", ["created_at"], {name: "index_jobler_jobs_on_created_at"})
+  }
+
+  /** @returns {Promise<void>} */
+  async down() {
+    await this.dropTable("jobler_jobs")
+  }
+}

package/src/frontend/job-progress-indicator.jsx

@@ -0,0 +1,206 @@
+// @ts-check
+/** @import {NamedExoticComponent, ReactNode} from "react" */
+import {memo, useEffect} from "react"
+import PropTypes from "prop-types"
+import {ActivityIndicator, StyleSheet, Text, View} from "react-native"
+import {shapeComponent, ShapeComponent} from "set-state-compare/build/shape-component"
+
+/**
+ * @typedef {object} JoblerJobModelLike
+ * @property {() => string} status
+ * @property {() => number} progressCurrent
+ * @property {() => number | null} progressTotal
+ * @property {() => string | null} statusMessage
+ * @property {() => string | null} errorMessage
+ */
+
+/**
+ * @typedef {object} JobProgressIndicatorProps
+ * @property {{findBy: (conditions: {id: string}) => Promise<JoblerJobModelLike | null>, onUpdate: (callback: (event: {id: string}) => void) => Promise<() => void>}} model - The jobler-job Velocious frontend-model class.
+ * @property {string} joblerJobId - Id of the jobler job to track.
+ * @property {(args: {errorMessage: string | null}) => void} [onFailed] - Called once when the job fails.
+ * @property {() => void} [onSucceeded] - Called once when the job succeeds.
+ * @property {{loading?: string, working?: string, failed?: string}} [labels] - Override the built-in English labels.
+ */
+
+/**
+ * @typedef {object} JobProgressIndicatorState
+ * @property {JoblerJobModelLike | null} joblerJob
+ */
+
+const DEFAULT_LABELS = {failed: "Failed", loading: "Loading…", working: "Working…"}
+
+/**
+ * Live progress for a jobler-tracked background job: loads the job through the given
+ * Velocious frontend-model, subscribes to its websocket updates, renders status, a
+ * progress bar and any message, and fires onSucceeded/onFailed once on a terminal
+ * status. Works with any status-bearing broadcasting frontend model.
+ */
+/** @type {NamedExoticComponent<JobProgressIndicatorProps>} */
+const JobProgressIndicator = memo(shapeComponent(
+  /** @augments {ShapeComponent<JobProgressIndicatorProps, JobProgressIndicatorState>} */
+  class JobProgressIndicator extends ShapeComponent {
+    static defaultProps = {
+      labels: undefined,
+      onFailed: undefined,
+      onSucceeded: undefined
+    }
+
+    static propTypes = {
+      joblerJobId: PropTypes.string.isRequired,
+      labels: PropTypes.object,
+      model: PropTypes.any.isRequired,
+      onFailed: PropTypes.func,
+      onSucceeded: PropTypes.func
+    }
+
+    /** @type {JobProgressIndicatorState} */
+    state = {
+      joblerJob: null
+    }
+
+    /** @type {boolean} */
+    terminalNotified = false
+
+    /** @returns {void} */
+    setup() {
+      useEffect(() => {
+        void this.loadData()
+      }, [this.p.joblerJobId])
+
+      useEffect(() => {
+        let stopped = false
+        /** @type {Array<() => void>} */
+        const unsubscribers = []
+
+        void this.subscribe(unsubscribers, () => stopped)
+
+        return () => {
+          stopped = true
+
+          for (const unsubscribe of unsubscribers) unsubscribe()
+        }
+      }, [this.p.joblerJobId])
+    }
+
+    /** @returns {Promise<void>} */
+    async loadData() {
+      const joblerJob = await this.p.model.findBy({id: this.p.joblerJobId})
+
+      this.s.joblerJob = joblerJob
+
+      if (joblerJob) {
+        this.notifyTerminalStatus(joblerJob)
+      }
+    }
+
+    /**
+     * @param {Array<() => void>} unsubscribers
+     * @param {() => boolean} stopped
+     * @returns {Promise<void>}
+     */
+    async subscribe(unsubscribers, stopped) {
+      const unsubscribe = await this.p.model.onUpdate(this.onJoblerJobUpdated)
+
+      if (stopped()) {
+        unsubscribe()
+
+        return
+      }
+
+      unsubscribers.push(unsubscribe)
+    }
+
+    /**
+     * @param {{id: string}} event
+     * @returns {void}
+     */
+    onJoblerJobUpdated = ({id}) => {
+      if (id !== this.p.joblerJobId) {
+        return
+      }
+
+      void this.loadData()
+    }
+
+    /**
+     * @param {JoblerJobModelLike} joblerJob
+     * @returns {void}
+     */
+    notifyTerminalStatus(joblerJob) {
+      if (this.terminalNotified) {
+        return
+      }
+
+      const status = joblerJob.status()
+
+      if (status === "succeeded") {
+        this.terminalNotified = true
+
+        if (this.p.onSucceeded) {
+          this.p.onSucceeded()
+        }
+      } else if (status === "failed") {
+        this.terminalNotified = true
+
+        if (this.p.onFailed) {
+          this.p.onFailed({errorMessage: joblerJob.errorMessage()})
+        }
+      }
+    }
+
+    /** @returns {ReactNode} */
+    render() {
+      const labels = {...DEFAULT_LABELS, ...this.p.labels}
+      const joblerJob = this.s.joblerJob
+
+      if (!joblerJob) {
+        return (
+          <View style={styles.row}>
+            <ActivityIndicator color="#93c5fd" />
+            <Text style={styles.message}>{labels.loading}</Text>
+          </View>
+        )
+      }
+
+      const status = joblerJob.status()
+      const inProgress = status === "pending" || status === "running"
+      const failed = status === "failed"
+      const progressTotal = joblerJob.progressTotal()
+      const statusMessage = joblerJob.statusMessage()
+      const jobErrorMessage = joblerJob.errorMessage()
+
+      return (
+        <View style={styles.wrap}>
+          <View style={styles.row}>
+            {inProgress && <ActivityIndicator color="#93c5fd" />}
+            <Text style={failed ? styles.statusFailed : styles.status}>
+              {failed ? labels.failed : (statusMessage || labels.working)}
+            </Text>
+          </View>
+          {progressTotal !== null && progressTotal > 0 && (
+            <View style={styles.progressTrack}>
+              <View style={[styles.progressFill, {width: /** @type {import("react-native").DimensionValue} */ (`${Math.min(100, Math.round((joblerJob.progressCurrent() / progressTotal) * 100))}%`)}]} />
+            </View>
+          )}
+          {failed && Boolean(jobErrorMessage) && <Text style={styles.error}>{jobErrorMessage}</Text>}
+        </View>
+      )
+    }
+  }
+))
+
+const styles = StyleSheet.create({
+  error: {color: "#fca5a5"},
+  message: {color: "#cbd5f5"},
+  progressFill: {backgroundColor: "#3b82f6", height: 6},
+  progressTrack: {backgroundColor: "#1e293b", borderRadius: 4, height: 6, overflow: "hidden"},
+  row: {alignItems: "center", flexDirection: "row", gap: 8},
+  status: {color: "#cbd5f5", fontWeight: "600"},
+  statusFailed: {color: "#fca5a5", fontWeight: "600"},
+  wrap: {gap: 8}
+})
+
+JobProgressIndicator.displayName = "JobProgressIndicator"
+
+export default JobProgressIndicator

package/src/model-bases/jobler-job.js

@@ -0,0 +1,238 @@
+// This file is auto-generated by Velocious. Do not edit it manually — any changes
+// will be overwritten the next time it is generated. Run `velocious generate:base-models` to regenerate.
+import DatabaseRecord from "velocious/build/src/database/record/index.js"
+
+/**
+ * Attributes accepted when creating or updating JoblerJob records.
+ * @typedef {object} JoblerJobWriteAttributes
+ * @property {string} [id] - Value for the id attribute.
+ * @property {string} [name] - Value for the name attribute.
+ * @property {string} [kind] - Value for the kind attribute.
+ * @property {string} [status] - Value for the status attribute.
+ * @property {number} [progressCurrent] - Value for the progressCurrent attribute.
+ * @property {number | null} [progressTotal] - Value for the progressTotal attribute.
+ * @property {string | null} [statusMessage] - Value for the statusMessage attribute.
+ * @property {string | null} [errorMessage] - Value for the errorMessage attribute.
+ * @property {string | null} [resultData] - Value for the resultData attribute.
+ * @property {Date | string | null} [startedAt] - Value for the startedAt attribute.
+ * @property {Date | string | null} [finishedAt] - Value for the finishedAt attribute.
+ * @property {Date | string | null} [createdAt] - Value for the createdAt attribute.
+ * @property {Date | string | null} [updatedAt] - Value for the updatedAt attribute.
+ */
+
+/** @augments {DatabaseRecord<JoblerJobWriteAttributes>} */
+export default class JoblerJobBase extends DatabaseRecord {
+  /**
+   * @returns {typeof import("../models/jobler-job.js").default}
+   */
+  // @ts-ignore - override narrows return type for better IntelliSense in generated model bases
+  getModelClass() { return /** @type {typeof import("../models/jobler-job.js").default} */ (this.constructor) }
+
+  /**
+   * @returns {string}
+   */
+  id() { return this.readAttribute("id") }
+
+  /**
+   * @param {string} newValue
+   * @returns {void}
+   */
+  setId(newValue) { return this._setColumnAttribute("id", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasId() { return this._hasAttribute(this.id()) }
+
+  /**
+   * @returns {string}
+   */
+  name() { return this.readAttribute("name") }
+
+  /**
+   * @param {string} newValue
+   * @returns {void}
+   */
+  setName(newValue) { return this._setColumnAttribute("name", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasName() { return this._hasAttribute(this.name()) }
+
+  /**
+   * @returns {string}
+   */
+  kind() { return this.readAttribute("kind") }
+
+  /**
+   * @param {string} newValue
+   * @returns {void}
+   */
+  setKind(newValue) { return this._setColumnAttribute("kind", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasKind() { return this._hasAttribute(this.kind()) }
+
+  /**
+   * @returns {string}
+   */
+  status() { return this.readAttribute("status") }
+
+  /**
+   * @param {string} newValue
+   * @returns {void}
+   */
+  setStatus(newValue) { return this._setColumnAttribute("status", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasStatus() { return this._hasAttribute(this.status()) }
+
+  /**
+   * @returns {number}
+   */
+  progressCurrent() { return this.readAttribute("progressCurrent") }
+
+  /**
+   * @param {number} newValue
+   * @returns {void}
+   */
+  setProgressCurrent(newValue) { return this._setColumnAttribute("progressCurrent", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasProgressCurrent() { return this._hasAttribute(this.progressCurrent()) }
+
+  /**
+   * @returns {number | null}
+   */
+  progressTotal() { return this.readAttribute("progressTotal") }
+
+  /**
+   * @param {number | null} newValue
+   * @returns {void}
+   */
+  setProgressTotal(newValue) { return this._setColumnAttribute("progressTotal", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasProgressTotal() { return this._hasAttribute(this.progressTotal()) }
+
+  /**
+   * @returns {string | null}
+   */
+  statusMessage() { return this.readAttribute("statusMessage") }
+
+  /**
+   * @param {string | null} newValue
+   * @returns {void}
+   */
+  setStatusMessage(newValue) { return this._setColumnAttribute("statusMessage", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasStatusMessage() { return this._hasAttribute(this.statusMessage()) }
+
+  /**
+   * @returns {string | null}
+   */
+  errorMessage() { return this.readAttribute("errorMessage") }
+
+  /**
+   * @param {string | null} newValue
+   * @returns {void}
+   */
+  setErrorMessage(newValue) { return this._setColumnAttribute("errorMessage", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasErrorMessage() { return this._hasAttribute(this.errorMessage()) }
+
+  /**
+   * @returns {string | null}
+   */
+  resultData() { return this.readAttribute("resultData") }
+
+  /**
+   * @param {string | null} newValue
+   * @returns {void}
+   */
+  setResultData(newValue) { return this._setColumnAttribute("resultData", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasResultData() { return this._hasAttribute(this.resultData()) }
+
+  /**
+   * @returns {Date | null}
+   */
+  startedAt() { return this.readAttribute("startedAt") }
+
+  /**
+   * @param {Date | string | null} newValue
+   * @returns {void}
+   */
+  setStartedAt(newValue) { return this._setColumnAttribute("startedAt", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasStartedAt() { return this._hasAttribute(this.startedAt()) }
+
+  /**
+   * @returns {Date | null}
+   */
+  finishedAt() { return this.readAttribute("finishedAt") }
+
+  /**
+   * @param {Date | string | null} newValue
+   * @returns {void}
+   */
+  setFinishedAt(newValue) { return this._setColumnAttribute("finishedAt", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasFinishedAt() { return this._hasAttribute(this.finishedAt()) }
+
+  /**
+   * @returns {Date | null}
+   */
+  createdAt() { return this.readAttribute("createdAt") }
+
+  /**
+   * @param {Date | string | null} newValue
+   * @returns {void}
+   */
+  setCreatedAt(newValue) { return this._setColumnAttribute("createdAt", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasCreatedAt() { return this._hasAttribute(this.createdAt()) }
+
+  /**
+   * @returns {Date | null}
+   */
+  updatedAt() { return this.readAttribute("updatedAt") }
+
+  /**
+   * @param {Date | string | null} newValue
+   * @returns {void}
+   */
+  setUpdatedAt(newValue) { return this._setColumnAttribute("updatedAt", newValue) }
+
+  /**
+   * @returns {boolean}
+   */
+  hasUpdatedAt() { return this._hasAttribute(this.updatedAt()) }
+}

package/src/models/jobler-job.js

@@ -0,0 +1,36 @@
+// @ts-check
+
+import JoblerJobBase from "../model-bases/jobler-job.js"
+
+export const JOBLER_JOB_STATUS_PENDING = "pending"
+export const JOBLER_JOB_STATUS_RUNNING = "running"
+export const JOBLER_JOB_STATUS_SUCCEEDED = "succeeded"
+export const JOBLER_JOB_STATUS_FAILED = "failed"
+export const JOBLER_JOB_STATUSES = [
+  JOBLER_JOB_STATUS_PENDING,
+  JOBLER_JOB_STATUS_RUNNING,
+  JOBLER_JOB_STATUS_SUCCEEDED,
+  JOBLER_JOB_STATUS_FAILED
+]
+
+/**
+ * Generic background-job progress record (a jobler-style tracker). Services create
+ * one before heavy async work and update its status/progress as it runs; the Expo
+ * UI subscribes to the broadcasting frontend model to show live progress.
+ */
+export default class JoblerJob extends JoblerJobBase {
+  /** @returns {void} */
+  beforeValidation() {
+    if (!this.hasStatus()) {
+      this.setStatus(JOBLER_JOB_STATUS_PENDING)
+    }
+
+    if (!this.hasProgressCurrent()) {
+      this.setProgressCurrent(0)
+    }
+  }
+}
+
+JoblerJob.validates("name", {presence: true})
+JoblerJob.validates("kind", {presence: true})
+JoblerJob.validates("status", {presence: true})

package/src/resources/jobler-job-resource.js

@@ -0,0 +1,33 @@
+// @ts-check
+
+import FrontendModelBaseResource from "velocious/build/src/frontend-model-resource/base-resource.js"
+import JoblerJob from "../models/jobler-job.js"
+
+/**
+ * JoblerJobResource — read-only. Only backend services create and update jobler
+ * jobs; clients just read them (and subscribe to live websocket updates). Only the
+ * `find` member command is exposed, so jobs can only be looked up individually by
+ * their unguessable uuid id — there is no `index`/list or `create` endpoint.
+ * @augments {FrontendModelBaseResource<typeof JoblerJob>}
+ */
+export default class JoblerJobResource extends FrontendModelBaseResource {
+  /** @type {typeof JoblerJob} */
+  static ModelClass = JoblerJob
+
+  /** @type {string[]} */
+  static attributes = ["id", "name", "kind", "status", "progressCurrent", "progressTotal", "statusMessage", "errorMessage", "resultData", "startedAt", "finishedAt", "createdAt", "updatedAt"]
+
+  // Explicitly empty: an undefined `builtInCollectionCommands` normalizes to the
+  // built-in `index` + `create` defaults, which would expose a list-every-job
+  // endpoint (cross-tenant leak) and let clients create jobs. Empty disables both.
+  /** @type {string[]} */
+  static builtInCollectionCommands = []
+
+  /** @type {string[]} */
+  static builtInMemberCommands = ["find"]
+
+  /** @returns {void} */
+  abilities() {
+    this.can(["read"])
+  }
+}

package/velocious-package.js

@@ -0,0 +1,5 @@
+// @ts-check
+
+import VelociousPackage from "velocious/build/src/packages/velocious-package.js"
+
+export default new VelociousPackage({name: "velocious-jobler", url: import.meta.url})