@stacksjs/action-runner 0.74.4

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @stacksjs/action-runner
+
+How a package runs an action by name, without depending on the action layer.
+
+Running an action belongs to `@stacksjs/actions`: it resolves the action file
+and spawns it. But three packages need to ask for that without *being* the
+action layer:
+
+- `@stacksjs/queue`, when a job names an action instead of handing over a function
+- `@stacksjs/scheduler`, for `Schedule.action('...')`
+- `@stacksjs/dns`, whose `addDomain` / `removeDomain` shell out to the domain actions
+
+and `@stacksjs/actions` imports all three. Importing it back closed a cycle in
+every case.
+
+So the capability is declared here, in a package that depends on nothing that
+can lead back to it, and `@stacksjs/actions` supplies it by the act of being
+imported at all.
+
+```ts
+import { runNamedAction } from '@stacksjs/action-runner'
+
+await runNamedAction('SendWelcomeEmail')
+```
+
+If nothing registered a runner, this falls back to importing `@stacksjs/actions`
+directly, and throws if that is not available either. It never silently does
+nothing: a job marked complete, or a scheduled task reported as run, with its
+work undone is the one outcome these callers must never produce.

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import type { Action } from '@stacksjs/enums';
+import type { ActionOptions } from '@stacksjs/types';
+/**
+ * Supply the runner. Called by `@stacksjs/actions` on import; an application
+ * embedding any of these packages on its own can call it with a runner of its
+ * own.
+ */
+export declare function setActionRunner(runner: ActionRunner): void;
+/** The registered runner, if the action layer has been loaded. */
+export declare function getActionRunner(): ActionRunner | null;
+/**
+ * Run an action by name.
+ *
+ * Prefers whatever registered itself. Falls back to importing the action
+ * package directly, because a worker or a scheduler process can reach a task
+ * before anything has pulled the action layer in - that import is the old
+ * behaviour, kept so this cannot break a caller that was working.
+ *
+ * When neither is available it throws. Silently doing nothing would leave a
+ * job marked complete, or a scheduled task reported as run, with its work
+ * undone - the one outcome these callers must never produce.
+ */
+export declare function runNamedAction(action: Action | string, options?: ActionOptions): Promise<any>;
+/**
+ * The options a runner accepts, matching `runAction`'s own second parameter.
+ * `DeployOptions` and friends are interfaces, so a structural stand-in like
+ * `Record<string, unknown>` would not accept them.
+ */
+export type ActionRunner = (action: Action | string, options?: ActionOptions) => Promise<any>;

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+var n=null;function e(t){n=t}function s(){return n}async function c(t,o){if(n)return await n(t,o);let i=await import("@stacksjs/actions").catch(()=>null);if(i?.runAction)return n=i.runAction,await n(t,o);throw Error(`Asked to run the action "${t}", but no action runner is available. Import @stacksjs/actions in this process, or register one with setActionRunner() from @stacksjs/action-runner.`)}export{s as getActionRunner,c as runNamedAction,e as setActionRunner};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@stacksjs/action-runner",
+  "type": "module",
+  "version": "0.74.4",
+  "description": "How a package runs an action by name, without depending on the action layer.",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/action-runner#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/action-runner"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "actions",
+    "runner",
+    "stacks"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "import": "./dist/*"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun --bun tsc --noEmit"
+  },
+  "dependencies": {
+    "@stacksjs/enums": "0.74.4",
+    "@stacksjs/types": "0.74.4"
+  }
+}