Added Standalone Activities sample

.github/workflows/ci.yml

@@ -64,6 +64,7 @@ jobs:
             mutex
             nestjs-exchange-rates
             sleep-for-days
+            standalone-activity
             timer-examples
             message-passing/introduction
             message-passing/safe-message-handlers

.scripts/list-of-samples.json

@@ -44,6 +44,7 @@
     "sinks",
     "sleep-for-days",
     "snippets",
+    "standalone-activity",
     "state",
     "timer-examples",
     "timer-progress",

README.md

@@ -104,6 +104,7 @@ and you'll be given the list of sample options.
   - `doSomethingAsync`: Complete an Activity async with [`AsyncCompletionClient`](https://typescript.temporal.io/api/classes/client.AsyncCompletionClient/#complete).
 - [**Activity Cancellation and Heartbeating**](./activities-cancellation-heartbeating): Heartbeat progress for long running activities and cancel them.
 - [**Dependency Injection**](./activities-dependency-injection): Share dependencies between activities (for example, when you need to initialize a database connection once and then pass it to multiple activities).
+- [**Standalone Activity**](./standalone-activity): Execute Activities directly from a Temporal Client, without a Workflow.
 - [**Worker-Specific Task Queues**](./worker-specific-task-queues): Use a unique task queue per Worker to have certain Activities only run on that specific Worker. For instance for a file processing Workflow, where the first Activity is downloading a file, and subsequent Activities need to operate on that file. (If multiple Workers were on the same queue, subsequent Activities may get run on different machines that don't have the downloaded file.)
 
 #### Nexus APIs

standalone-activity/.eslintignore

@@ -0,0 +1,3 @@
+node_modules
+lib
+.eslintrc.js

standalone-activity/.eslintrc.js

@@ -0,0 +1,48 @@
+const { builtinModules } = require('module');
+
+const ALLOWED_NODE_BUILTINS = new Set(['assert']);
+
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
+  },
+  plugins: ['@typescript-eslint', 'deprecation'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/eslint-recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier',
+  ],
+  rules: {
+    // recommended for safety
+    '@typescript-eslint/no-floating-promises': 'error', // forgetting to await Activities and Workflow APIs is bad
+    'deprecation/deprecation': 'warn',
+
+    // code style preference
+    'object-shorthand': ['error', 'always'],
+
+    // relaxed rules, for convenience
+    '@typescript-eslint/no-unused-vars': [
+      'warn',
+      {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+      },
+    ],
+    '@typescript-eslint/no-explicit-any': 'off',
+  },
+  overrides: [
+    {
+      files: ['src/workflows.ts', 'src/workflows-*.ts', 'src/workflows/*.ts'],
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          ...builtinModules.filter((m) => !ALLOWED_NODE_BUILTINS.has(m)).flatMap((m) => [m, `node:${m}`]),
+        ],
+      },
+    },
+  ],
+};

standalone-activity/.gitignore

@@ -0,0 +1,2 @@
+lib
+node_modules

standalone-activity/.npmrc

@@ -0,0 +1 @@
+package-lock=false

standalone-activity/.nvmrc

@@ -0,0 +1 @@
+22

standalone-activity/.post-create

@@ -0,0 +1,18 @@
+To begin development, install the Temporal CLI:
+
+Mac: {cyan brew install temporal}
+Other: Download and extract the latest release from https://github.com/temporalio/cli/releases/latest
+
+Start Temporal Server:
+
+{cyan temporal server start-dev}
+
+Use Node version 18+ (v22.x is recommended):
+
+Mac: {cyan brew install node@22}
+Other: https://nodejs.org/en/download/
+
+Then, in the project directory, using two other shells, run these commands:
+
+{cyan npm run start.watch}
+{cyan npm run workflow}

standalone-activity/.prettierignore

@@ -0,0 +1 @@
+lib

standalone-activity/.prettierrc

@@ -0,0 +1,2 @@
+printWidth: 120
+singleQuote: true

standalone-activity/README.md

@@ -0,0 +1,21 @@
+# Standalone Activity
+
+This sample shows how to execute Activities directly from a Temporal Client, without a Workflow.
+
+### Running this sample
+
+1. `temporal server start-dev` to start [Temporal Server](https://github.com/temporalio/cli/#installation).
+1. `npm install` to install dependencies.
+1. `npm run start.watch` to start the Worker.
+1. In another shell, `npm run execute` to execute the activity in different ways.
+
+Example output:
+
+```
+Hello, Temporal!
+Hello, World!
+Hello, Temporal!
+Oops! name must be a string
+```
+
+Afterwards, you can run `npm run list` to see a listing of activity executions.

standalone-activity/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "temporal-standalone-activity",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc --build",
+    "build.watch": "tsc --build --watch",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "start": "ts-node src/worker.ts",
+    "start.watch": "nodemon src/worker.ts",
+    "execute": "ts-node src/execute.ts",
+    "list": "ts-node src/list.ts",
+    "test": "mocha --exit --require ts-node/register --require source-map-support/register src/mocha/*.test.ts"
+  },
+  "nodemonConfig": {
+    "execMap": {
+      "ts": "ts-node"
+    },
+    "ext": "ts",
+    "watch": [
+      "src"
+    ]
+  },
+  "dependencies": {
+    "@temporalio/activity": "^1.17.0",
+    "@temporalio/client": "^1.17.0",
+    "@temporalio/envconfig": "^1.17.0",
+    "@temporalio/worker": "^1.17.0",
+    "nanoid": "3.x"
+  },
+  "devDependencies": {
+    "@temporalio/testing": "^1.17.0",
+    "@tsconfig/node22": "^22.0.0",
+    "@types/mocha": "8.x",
+    "@types/node": "^22.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-deprecation": "^3.0.0",
+    "mocha": "8.x",
+    "nodemon": "^3.1.7",
+    "prettier": "^3.4.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.3"
+  }
+}

standalone-activity/src/activities.ts

@@ -0,0 +1,8 @@
+import { ApplicationFailure } from '@temporalio/activity';
+
+export async function greet(name: string): Promise<string> {
+  if (typeof name !== 'string') {
+    throw ApplicationFailure.create({ message: 'name must be a string', nonRetryable: true });
+  }
+  return `Hello, ${name}!`;
+}

standalone-activity/src/execute.ts

@@ -0,0 +1,62 @@
+import { Connection, Client, ActivityExecutionFailedError } from '@temporalio/client';
+import { loadClientConnectConfig } from '@temporalio/envconfig';
+import * as activities from './activities';
+import { nanoid } from 'nanoid';
+
+async function run() {
+  const config = loadClientConnectConfig();
+  const connection = await Connection.connect(config.connectionOptions);
+  const client = new Client({ connection });
+
+  // Typed client interface ensures activity names and argument types are all correct at build time
+  const activitiesClient = client.activity.typed<typeof activities>();
+
+  const taskQueue = 'hello-standalone-activities';
+  const activityOptions = {
+    taskQueue,
+    startToCloseTimeout: '10s',
+  };
+
+  // In practice, use a meaningful business ID, like customer ID or transaction ID
+  const activityId = nanoid();
+
+  // Handle can be used to get information and control the activity
+  const handle = await activitiesClient.start('greet', {
+    ...activityOptions,
+    id: activityId,
+    args: ['Temporal'],
+  });
+
+  // Optional: wait for activity result
+  console.log(await handle.result()); // Hello, Temporal!
+
+  // `execute` allows starting the activity and getting the result in one go
+  const result = await activitiesClient.execute('greet', {
+    ...activityOptions,
+    id: activityId + '-2',
+    args: ['World'],
+  });
+  console.log(result); // Hello, World!
+
+  // If needed, activity handle can be recreated from just activity ID, although with weaker type safety
+  const newHandle = client.activity.getHandle<string>(activityId);
+  console.log(await newHandle.result()); // Hello, Temporal!
+
+  // Activity client can execute activities without the typed interface - useful when activity declarations are unavailable
+  try {
+    await client.activity.execute('greet', {
+      ...activityOptions,
+      id: activityId + '-3',
+      args: [1],
+    });
+  } catch (err) {
+    if (err instanceof ActivityExecutionFailedError) {
+      console.log('Oops!', err.cause?.message); // Oops! name must be a string
+    }
+  }
+}
+
+run().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

standalone-activity/src/list.ts

@@ -0,0 +1,27 @@
+import { Connection, Client } from '@temporalio/client';
+import { loadClientConnectConfig } from '@temporalio/envconfig';
+
+async function run() {
+  const config = loadClientConnectConfig();
+  const connection = await Connection.connect(config.connectionOptions);
+  const client = new Client({ connection });
+
+  // Documentation for query syntax available at https://docs.temporal.io/list-filter
+  const query = 'TaskQueue="hello-standalone-activities"';
+
+  const { count } = await client.activity.count(query);
+  console.log(`Total activities: ${count}`);
+
+  console.log('ACTIVITY ID | RUN ID | ACTIVITY TYPE | STATUS | COMPLETED TIME');
+
+  for await (const a of client.activity.list(query)) {
+    console.log(
+      `${a.activityId} | ${a.activityRunId} | ${a.activityType} | ${a.status} | ${a.closeTime?.toISOString()}`,
+    );
+  }
+}
+
+run().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});