add media scanner workflow example (#4589)

* add media scanner workflow example

* update readme. remove unnecessary import

* Format readme

---------

Co-authored-by: David Khourshid <davidkpiano@gmail.com>

examples/workflow-media-scanner/.gitignore

@@ -0,0 +1,130 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*

examples/workflow-media-scanner/README.md

@@ -0,0 +1,126 @@
+# Workflow Example: Scanning and spliting Media
+
+This is a small example of a back-end workflow that uses a state machine to execute long running tasks. This project crawls a directory full of movies and separates out videos over 1080p for potential processing down the line.
+
+> **NOTE:This project is not intended for production use.**
+
+## Prerequisites
+
+This project requires `ffprobe`, a binary that ships alongside `ffmpeg`, which is the golden standard for media file manipulation.
+
+- [Install ffmpeg here](https://ffmpeg.org/download.html)
+- Clone this repo and run `yarn` (or use your package manager of choice) in a terminal at the project's root.
+- Update the `basePath` and `destinationPath` in the `mediaScannerMachine.ts` file with your own paths.
+- Run the project with `yarn start` in the terminal
+
+## XState concepts involved
+
+This project convers how to implement the following with XState:
+
+- Initializing a XState machine as an actor
+
+  ```ts
+  // index.ts
+
+  // ...
+
+  const mediaScannerActor = createActor(mediaScannerMachine);
+  ```
+
+- Injecting context information into the actor on initialization
+
+  ```ts
+  // index.ts
+
+  // ...
+
+  const mediaScannerActor = createActor(mediaScannerMachine, {
+    input: {
+      basePath: 'YOUR BASE PATH HERE',
+      destinationPath: 'YOUR DESTINATION PATH HERE'
+    }
+  });
+  ```
+
+- Sending events to the XState actor
+
+  ```ts
+  // index.ts
+
+  // ...
+
+  mediaScannerActor.send({ type: 'START_SCAN' });
+  ```
+
+- Subscribing to a running actor for state change and context information
+
+  ```ts
+  // index.ts
+
+  // ...
+
+  mediaScannerActor.subscribe((state) => {
+    console.log({
+      state: state.value,
+      error: state.error,
+      context: state.context
+    });
+  });
+  ```
+
+- Invoking services and capturing results
+
+  > mediaScannerMachine.ts
+
+  ```ts
+  invoke: {
+    id: 'checkFilePermissions',
+    input: ({ context: { directoriesToCheck } }) => ({
+      directoriesToCheck
+    }),
+    src: fromPromise(async ({ input: { directoriesToCheck } }) =>
+      await checkFilePermissions(directoriesToCheck)
+    ),
+    onDone: [
+      {
+        target: 'EvaluatingFiles',
+        actions: assign(({ event }) => {
+          return {
+            dirsToEvaluate: event.output['dirsToEvaluate'],
+            dirsToReport: event.output['dirsToReport']
+          };
+        })
+      }
+    ],
+    onError: [
+      {
+        target: 'ReportingErrors',
+        actions: assign(({ event }) => {
+          return {
+            dirsToReport: event.error['dirsToReport']
+          };
+        })
+      }
+    ]
+  }
+  ```
+
+- Batching results and assigning multiple properties to the actor's context
+
+  > fileHandlers.ts
+
+  ```ts
+  ...
+   return { dirsToEvaluate, dirsToReport };
+  ```
+
+  > mediaScannerMachine.ts
+
+  ```ts
+  actions: assign(({ event }) => {
+    return {
+      dirsToEvaluate: event.output['dirsToEvaluate'],
+      dirsToReport: event.output['dirsToReport']
+    };
+  });
+  ```

examples/workflow-media-scanner/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "mediaScanner",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "scripts": {
+    "start": "ts-node src/index.ts"
+  },
+  "dependencies": {
+    "@types/node": "^20.10.3",
+    "fs-extra": "^11.2.0",
+    "mv": "^2.1.1",
+    "node-ffprobe": "^3.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.2",
+    "winston": "^3.11.0",
+    "xstate": "^5.0.0"
+  }
+}