sails-hook-quest 0.0.4 → 0.0.6

package/lib/core/job-control.js

@@ -1,9 +1,22 @@
+// @ts-check
+
 /**
  * core/job-control.js
  *
  * Functions for controlling job lifecycle (start, stop, pause, resume)
  */
 
+const { getGlobalSails } = require('./global-sails')
+
+/** @typedef {import('../types').AnyRecord} AnyRecord */
+/** @typedef {import('../types').QuestExecutionResult} QuestExecutionResult */
+/** @typedef {import('../types').QuestJobNameInput} QuestJobNameInput */
+/** @typedef {import('../types').QuestJobsMap} QuestJobsMap */
+/** @typedef {import('../types').QuestRunContext} QuestRunContext */
+/** @typedef {import('../types').QuestScheduleContext} QuestScheduleContext */
+/** @typedef {import('../types').QuestStartContext} QuestStartContext */
+/** @typedef {import('../types').QuestStopContext} QuestStopContext */
+
 // setTimeout uses a 32-bit signed integer internally.
 // Delays larger than this overflow and fire immediately (~1ms), causing infinite loops.
 const MAX_SAFE_TIMEOUT = 2_147_483_647 // 2^31 - 1, ~24.8 days
@@ -11,31 +24,60 @@ const MAX_SAFE_TIMEOUT = 2_147_483_647 // 2^31 - 1, ~24.8 days
 /**
  * Schedule a job to run at its next scheduled time
  * @param {String} name - Job name
- * @param {Object} context - Context with jobs, timers maps and helper functions
+ * @param {QuestScheduleContext} [context] - Context with jobs, timers maps and helper functions
+ * @param {Date} [targetTime] - Original target for a long-delay intermediate timer
  */
-function scheduleJob(name, context = {}) {
-  const {
-    jobs = new Map(),
-    timers = new Map(),
-    getNextRunTime,
-    executeJob
-  } = context
+function scheduleJob(name, context = {}, targetTime) {
+  const { jobs = new Map(), timers = new Map() } = context
+  const getNextRunTime =
+    /** @type {NonNullable<QuestScheduleContext['getNextRunTime']>} */ (
+      context.getNextRunTime
+    )
+  const executeJob =
+    /** @type {NonNullable<QuestScheduleContext['executeJob']>} */ (
+      context.executeJob
+    )
 
   const job = jobs.get(name)
   if (!job) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.warn(`Job "${name}" not found in jobs Map`)
     }
     return
   }
 
   // Clear any existing timer
-  stopJob(name, { timers })
+  stopJob(name, context)
 
   // Get the next run time
-  const nextRun = getNextRunTime(job)
+  const states = context.scheduleStates
+  const update = (registration) =>
+    states?.set(name, {
+      validation: 'not_checked',
+      validationErrors: [],
+      reason: null,
+      ...states.get(name),
+      registration
+    })
+  if (states && !targetTime)
+    states.set(name, {
+      validation: 'not_checked',
+      validationErrors: [],
+      reason: null,
+      lastAttemptAt: new Date().toISOString(),
+      registration: 'not_registered'
+    })
+  let nextRun
+  try {
+    nextRun = targetTime || getNextRunTime(job)
+  } catch (err) {
+    update('failed')
+    throw err
+  }
   if (!nextRun) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.warn(
         `Job "${name}" has no valid schedule (interval: ${job.interval}, cron: ${job.cron}, timeout: ${job.timeout})`
       )
@@ -43,12 +85,32 @@ function scheduleJob(name, context = {}) {
     return
   }
 
+  if (!Number.isFinite(nextRun.getTime())) {
+    states?.set(name, {
+      ...states.get(name),
+      registration: 'failed',
+      validation: 'invalid',
+      reason: null,
+      validationErrors: [
+        {
+          code: 'E_SCHEDULE_TARGET',
+          message: 'Schedule target must be a finite date.'
+        }
+      ]
+    })
+    return
+  }
   const delay = nextRun.getTime() - Date.now()
+  context.dueTimes?.set(name, nextRun)
 
   // If delay is negative (past time), run immediately
   if (delay <= 0) {
-    executeJob(name).catch((err) => {
-      if (global.sails) {
+    timers.delete(name)
+    context.dueTimes?.delete(name)
+    update('consumed')
+    executeJob(name, undefined, 'scheduled').catch((err) => {
+      const sails = getGlobalSails()
+      if (sails) {
         sails.log.error(`Error running job "${name}":`, err)
       }
     })
@@ -64,12 +126,14 @@ function scheduleJob(name, context = {}) {
   // that rechecks when we're closer to the target time
   if (delay > MAX_SAFE_TIMEOUT) {
     const timer = setTimeout(() => {
-      scheduleJob(name, context)
+      scheduleJob(name, context, nextRun)
     }, MAX_SAFE_TIMEOUT)
 
     timers.set(name, timer)
+    update('registered')
 
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.verbose(
         `Job "${name}" scheduled for ${nextRun.toISOString()} (delay exceeds 24.8d, re-checking later)`
       )
@@ -79,8 +143,12 @@ function scheduleJob(name, context = {}) {
 
   // Set timer for the next execution
   const timer = setTimeout(() => {
-    executeJob(name).catch((err) => {
-      if (global.sails) {
+    timers.delete(name)
+    context.dueTimes?.delete(name)
+    update('consumed')
+    executeJob(name, undefined, 'scheduled').catch((err) => {
+      const sails = getGlobalSails()
+      if (sails) {
         sails.log.error(`Error running job "${name}":`, err)
       }
     })
@@ -92,8 +160,10 @@ function scheduleJob(name, context = {}) {
   }, delay)
 
   timers.set(name, timer)
+  update('registered')
 
-  if (global.sails) {
+  const sails = getGlobalSails()
+  if (sails) {
     sails.log.verbose(`Job "${name}" scheduled for ${nextRun.toISOString()}`)
   }
 }
@@ -101,17 +171,31 @@ function scheduleJob(name, context = {}) {
 /**
  * Stop a single job
  * @param {String} name - Job name
- * @param {Object} context - Context with timers map
+ * @param {QuestStopContext} [context] - Context with timers map
  */
 function stopJob(name, context = {}) {
   const { timers = new Map() } = context
 
+  context.dueTimes?.delete(name)
+  if (
+    context.scheduleStates &&
+    (context.scheduleStates.has(name) || context.jobs?.has(name))
+  )
+    context.scheduleStates.set(name, {
+      validation: 'not_checked',
+      validationErrors: [],
+      reason: null,
+      lastAttemptAt: null,
+      ...context.scheduleStates.get(name),
+      registration: 'stopped'
+    })
   const timer = timers.get(name)
   if (timer) {
     clearTimeout(timer)
     clearInterval(timer)
     timers.delete(name)
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.verbose(`Job "${name}" stopped`)
     }
   }
@@ -119,11 +203,16 @@ function stopJob(name, context = {}) {
 
 /**
  * Start scheduling jobs
- * @param {String|Array} jobNames - Job names to start (optional)
- * @param {Object} context - Context with jobs map and scheduleJob function
+ * @param {QuestJobNameInput} jobNames - Job names to start (optional)
+ * @param {QuestStartContext} [context] - Context with jobs map and scheduleJob function
+ * @returns {Promise<void>}
  */
 async function startJobs(jobNames, context = {}) {
-  const { jobs = new Map(), scheduleJob } = context
+  const { jobs = new Map() } = context
+  const scheduleJob =
+    /** @type {NonNullable<QuestStartContext['scheduleJob']>} */ (
+      context.scheduleJob
+    )
 
   const names = !jobNames
     ? Array.from(jobs.keys())
@@ -138,8 +227,9 @@ async function startJobs(jobNames, context = {}) {
 
 /**
  * Stop scheduling jobs
- * @param {String|Array} jobNames - Job names to stop (optional)
- * @param {Object} context - Context with jobs and timers maps
+ * @param {QuestJobNameInput} jobNames - Job names to stop (optional)
+ * @param {QuestStopContext} [context] - Context with jobs and timers maps
+ * @returns {void}
  */
 function stopJobs(jobNames, context = {}) {
   const { jobs = new Map(), timers = new Map() } = context
@@ -151,18 +241,22 @@ function stopJobs(jobNames, context = {}) {
       : [jobNames]
 
   for (const name of names) {
-    stopJob(name, { timers })
+    stopJob(name, context)
   }
 }
 
 /**
  * Run jobs immediately
- * @param {String|Array} jobNames - Job names to run
- * @param {Object} inputs - Custom inputs
- * @param {Object} context - Context with executeJob function
+ * @param {QuestJobNameInput} jobNames - Job names to run
+ * @param {AnyRecord} [inputs] - Custom inputs
+ * @param {QuestRunContext} [context] - Context with executeJob function
+ * @returns {Promise<QuestExecutionResult[]>}
  */
 async function runJobs(jobNames, inputs, context = {}) {
-  const { jobs = new Map(), executeJob } = context
+  const { jobs = new Map() } = context
+  const executeJob = /** @type {NonNullable<QuestRunContext['executeJob']>} */ (
+    context.executeJob
+  )
 
   const names = !jobNames
     ? Array.from(jobs.keys())
@@ -170,14 +264,15 @@ async function runJobs(jobNames, inputs, context = {}) {
       ? jobNames
       : [jobNames]
 
-  const promises = names.map((name) => executeJob(name, inputs))
+  const promises = names.map((name) => executeJob(name, inputs, 'manual'))
   return Promise.all(promises)
 }
 
 /**
  * Pause a job
  * @param {String} name - Job name
- * @param {Map} jobs - Jobs map
+ * @param {QuestJobsMap} [jobs] - Jobs map
+ * @returns {boolean}
  */
 function pauseJob(name, jobs = new Map()) {
   const job = jobs.get(name)
@@ -191,7 +286,8 @@ function pauseJob(name, jobs = new Map()) {
 /**
  * Resume a job
  * @param {String} name - Job name
- * @param {Map} jobs - Jobs map
+ * @param {QuestJobsMap} [jobs] - Jobs map
+ * @returns {boolean}
  */
 function resumeJob(name, jobs = new Map()) {
   const job = jobs.get(name)

package/lib/core/loader.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * core/loader.js
  *
@@ -6,13 +8,24 @@
 
 const path = require('path')
 const includeAll = require('include-all')
+const { getGlobalSails } = require('./global-sails')
+
+/** @typedef {import('../types').AnyRecord} AnyRecord */
+/** @typedef {import('../types').QuestConfig} QuestConfig */
+/** @typedef {import('../types').QuestJob} QuestJob */
+/** @typedef {import('../types').QuestJobDefinition} QuestJobDefinition */
+/** @typedef {import('../types').QuestJobsMap} QuestJobsMap */
+/** @typedef {import('../types').QuestMachineInputs} QuestMachineInputs */
+/** @typedef {import('../types').QuestScriptDefinition} QuestScriptDefinition */
+/** @typedef {import('../types').QuestTimersMap} QuestTimersMap */
 
 /**
  * Extract default values from a script's inputs schema
- * @param {Object} inputs - Script's inputs definition (Sails machine format)
- * @returns {Object} Object with input names and their defaultsTo values
+ * @param {QuestMachineInputs | null | undefined} inputs - Script's inputs definition (Sails machine format)
+ * @returns {AnyRecord} Object with input names and their defaultsTo values
  */
 function extractScriptInputDefaults(inputs) {
+  /** @type {AnyRecord} */
   const defaults = {}
   if (!inputs || typeof inputs !== 'object') return defaults
 
@@ -26,9 +39,9 @@ function extractScriptInputDefaults(inputs) {
 
 /**
  * Load jobs from scripts directory and config
- * @param {Object} config - Quest configuration
- * @param {Map} jobs - Jobs map to populate
- * @returns {Promise<Map>} Populated jobs map
+ * @param {QuestConfig} config - Quest configuration
+ * @param {QuestJobsMap} [jobs] - Jobs map to populate
+ * @returns {Promise<QuestJobsMap>} Populated jobs map
  */
 async function loadJobs(config, jobs = new Map()) {
   // First, load scripts from the scripts directory
@@ -36,17 +49,21 @@ async function loadJobs(config, jobs = new Map()) {
   const appPath = config.appPath || process.cwd()
   const fullPath = path.resolve(appPath, scriptsDir)
 
+  /** @type {Record<string, QuestScriptDefinition>} */
   let scripts = {}
 
   try {
-    scripts = includeAll({
-      dirname: fullPath,
-      filter: /(.+)\.js$/,
-      excludeDirs: /^\.(git|svn)$/,
-      flatten: true
-    })
+    scripts = /** @type {Record<string, QuestScriptDefinition>} */ (
+      includeAll({
+        dirname: fullPath,
+        filter: /(.+)\.js$/,
+        excludeDirs: /^\.(git|svn)$/,
+        flatten: true
+      })
+    )
   } catch (e) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.verbose('No scripts directory found, skipping script jobs')
     }
   }
@@ -57,22 +74,28 @@ async function loadJobs(config, jobs = new Map()) {
 
     for (const jobDef of config.jobs) {
       // Handle string shorthand (just job name)
-      const job = typeof jobDef === 'string' ? { name: jobDef } : jobDef
+      /** @type {QuestJobDefinition} */
+      const job = typeof jobDef === 'string' ? { name: jobDef } : { ...jobDef }
+      const jobName = job.name
 
       // Check for duplicate job names in config
-      if (configJobNames.has(job.name)) {
+      if (jobName && configJobNames.has(jobName)) {
         throw new Error(
-          `Duplicate job name "${job.name}" in config/quest.js. Each job must have a unique name.`
+          `Duplicate job name "${jobName}" in config/quest.js. Each job must have a unique name.`
         )
       }
-      configJobNames.add(job.name)
+      if (jobName) {
+        configJobNames.add(jobName)
+      }
 
       // Try to get script inputs if the script exists
-      const scriptDef = scripts[job.name]
+      const scriptDef = jobName ? scripts[job.script || jobName] : undefined
       if (scriptDef && !job.scriptInputs) {
         job.scriptInputs = extractScriptInputDefaults(scriptDef.inputs)
       }
 
+      job.script = job.script || jobName
+      job.inputSchema = scriptDef ? scriptDef.inputs || {} : undefined
       addJobDefinition(job, jobs, config)
     }
   }
@@ -92,15 +115,18 @@ async function loadJobs(config, jobs = new Map()) {
     const existingJob = jobs.get(jobName)
 
     // Merge: config as base, script quest config takes priority
+    /** @type {QuestJobDefinition} */
     const jobDef = {
       name: jobName,
       friendlyName: scriptDef.friendlyName,
       description: scriptDef.description,
       // Preserve config's withoutOverlapping if script doesn't specify
       withoutOverlapping: existingJob?.withoutOverlapping,
-      inputs: { ...existingJob?.inputs, ...questConfig.inputs },
+      inputs: { ...(existingJob?.inputs || {}), ...(questConfig.inputs || {}) },
       ...questConfig,
-      scriptInputs
+      scriptInputs,
+      script: scriptName,
+      inputSchema: scriptDef.inputs || {}
     }
 
     addJobDefinition(jobDef, jobs, config)
@@ -111,23 +137,27 @@ async function loadJobs(config, jobs = new Map()) {
 
 /**
  * Add a job definition to the jobs Map
- * @param {Object} jobDef - Job definition
- * @param {Map} jobs - Jobs map
- * @param {Object} config - Quest configuration
- * @returns {Object} Normalized job
+ * @param {QuestJobDefinition} jobDef - Job definition
+ * @param {QuestJobsMap} [jobs] - Jobs map
+ * @param {QuestConfig} [config] - Quest configuration
+ * @returns {QuestJob | null} Normalized job
  */
 function addJobDefinition(jobDef, jobs = new Map(), config = {}) {
   const name = jobDef.name
   if (!name) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.warn('Job definition missing name, skipping:', jobDef)
     }
     return null
   }
 
   // Parse and normalize the job definition
+  /** @type {QuestJob} */
   const job = {
     name,
+    script: jobDef.script || name,
+    inputSchema: jobDef.inputSchema,
     friendlyName: jobDef.friendlyName || name,
     description: jobDef.description,
 
@@ -151,7 +181,8 @@ function addJobDefinition(jobDef, jobs = new Map(), config = {}) {
 
   jobs.set(name, job)
 
-  if (global.sails) {
+  const sails = getGlobalSails()
+  if (sails) {
     const schedule = {}
     if (job.interval !== undefined) schedule.interval = job.interval
     if (job.cron !== undefined) schedule.cron = job.cron
@@ -165,8 +196,8 @@ function addJobDefinition(jobDef, jobs = new Map(), config = {}) {
 /**
  * Remove a job from the jobs map
  * @param {String} name - Job name
- * @param {Map} jobs - Jobs map
- * @param {Map} timers - Timers map
+ * @param {QuestJobsMap} [jobs] - Jobs map
+ * @param {QuestTimersMap} [timers] - Timers map
  * @returns {Boolean} Success
  */
 function removeJob(name, jobs = new Map(), timers = new Map()) {
@@ -181,7 +212,8 @@ function removeJob(name, jobs = new Map(), timers = new Map()) {
   // Remove from jobs map
   const existed = jobs.delete(name)
 
-  if (existed && global.sails) {
+  const sails = getGlobalSails()
+  if (existed && sails) {
     sails.log.verbose(`Job "${name}" removed`)
   }
 

package/lib/core/result.js

@@ -0,0 +1,91 @@
+// @ts-check
+
+const DEFAULT_RESULT_BYTES = 64 * 1024
+const MAX_RESULT_BYTES = 1024 * 1024
+
+/** @param {number} [value] */
+function byteLimit(value) {
+  return Number.isFinite(value) && value > 0
+    ? Math.min(MAX_RESULT_BYTES, Math.floor(value))
+    : DEFAULT_RESULT_BYTES
+}
+
+/**
+ * Encode plain JSON without executing getters/toJSON or allocating an unbounded
+ * intermediate JSON string. Depth/node limits bound even tiny nested values.
+ * @param {any} value
+ * @param {number} [requestedBytes]
+ * @returns {{status: string, value?: any, json?: string, exit?: string}}
+ */
+function encodeResult(value, requestedBytes) {
+  if (value === undefined) return { status: 'undefined' }
+  const limit = byteLimit(requestedBytes)
+  const parts = []
+  const ancestors = new Set()
+  let bytes = 0
+  let nodes = 0
+  function append(text) {
+    bytes += Buffer.byteLength(text)
+    if (bytes > limit) throw new RangeError('too_large')
+    parts.push(text)
+  }
+  function visit(item, depth) {
+    if (++nodes > 10000 || depth > 64) throw new RangeError('too_large')
+    if (item === null) return append('null')
+    if (typeof item === 'boolean') return append(String(item))
+    if (typeof item === 'number' && Number.isFinite(item))
+      return append(String(item))
+    if (typeof item === 'string') {
+      if (
+        item.length > limit - bytes ||
+        Buffer.byteLength(item) > limit - bytes
+      )
+        throw new RangeError('too_large')
+      return append(JSON.stringify(item))
+    }
+    if (typeof item !== 'object') throw new TypeError('non_json')
+    if (ancestors.has(item)) throw new TypeError('circular')
+    const array = Array.isArray(item)
+    if (
+      !array &&
+      Object.getPrototypeOf(item) !== Object.prototype &&
+      Object.getPrototypeOf(item) !== null
+    ) {
+      throw new TypeError('non_plain_object')
+    }
+    ancestors.add(item)
+    append(array ? '[' : '{')
+    const keys = array ? null : Object.keys(item)
+    const count = array ? item.length : keys.length
+    if (count > 10000) throw new RangeError('too_large')
+    for (let i = 0; i < count; i++) {
+      if (i) append(',')
+      const key = array ? String(i) : keys[i]
+      if (!array) {
+        if (
+          key.length > limit - bytes ||
+          Buffer.byteLength(key) > limit - bytes
+        )
+          throw new RangeError('too_large')
+        append(JSON.stringify(key) + ':')
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(item, key)
+      if (!descriptor || !('value' in descriptor))
+        throw new TypeError('non_json_property')
+      visit(descriptor.value, depth + 1)
+    }
+    append(array ? ']' : '}')
+    ancestors.delete(item)
+  }
+  try {
+    visit(value, 0)
+    const json = parts.join('')
+    return { status: 'available', value: JSON.parse(json), json }
+  } catch (error) {
+    return {
+      status: error instanceof RangeError ? 'too_large' : 'serialization_error'
+    }
+  }
+}
+
+module.exports = { encodeResult, byteLimit }