Merge pull request #57 from SeasonedSoftware/trace-function

Create a trace function that will capture the inputs and outputs of any DF and call an arbitraty function.

README.md

@@ -19,6 +19,7 @@ It does this by enforcing the parameters' types in runtime (through [zod](https:
   - [Using error messages in the UI](#using-error-messages-in-the-ui)
     - [errorMessagesFor](#errormessagesfor)
     - [errorMessagesForSchema](#errormessagesforschema)
+  - [Tracing](#tracing)
 - [Combining domain functions](#combining-domain-functions)
   - [all](#all)
   - [first](#first)
@@ -296,6 +297,35 @@ errorMessagesForSchema(result.inputErrors, schema)
 */
 ```
 
+### Tracing
+Whenever you need to intercept inputs and the result of a domain function without changing them, there is a function called `trace` that can help you..
+
+The most common use case is to log failures to the console or to an external service. Let's say you want to log failed domain functions, you could create a function such as:
+
+```ts
+const traceToConsole = trace((context) => {
+  if(!context.result.success) {
+    console.trace("Domain Function Failure ", context)
+  }
+})
+```
+
+Then, assuming you want to trace all failures in a `someOtherDomainFunction`, you just need to pass that domain function to our `tracetoConsole`:
+
+```ts
+traceToConsole(someOtherDomainFunction)()
+```
+
+It would be also simple to create a function that will send the errors to some error tracking service upon certain conditions:
+
+```ts
+const trackErrors = trace(({ input, output, result }) => {
+  if(!result.success && someOtherConditions(result)) {
+    sendToExternalService({ input, output, result })
+  }
+})
+```
+
 ## Combining domain functions
 These combinators are useful for composing domain functions. The returning type of all of them is another `DomainFunction` thus allowing further application in more compositions.
 

src/domain-function.test.ts

@@ -17,14 +17,15 @@ import {
   first,
   merge,
   sequence,
+trace,
 } from './domain-functions.ts'
 import {
   EnvironmentError,
   ResultError,
   InputError,
   InputErrors,
 } from './errors.ts'
-import type { ErrorData, SuccessResult } from './types.ts'
+import type { ErrorData, Result, SuccessResult } from './types.ts'
 
 describe('makeDomainFunction', () => {
   describe('when it has no input', async () => {
@@ -1060,3 +1061,31 @@ describe('fromSuccess', () => {
     }, ResultError)
   })
 })
+
+describe('trace', () => {
+  it('intercepts inputs and outputs of a given domain function', async () => {
+    const a = makeDomainFunction(z.object({ id: z.number() }))(
+      async ({ id }) => id + 1,
+    )
+
+    let contextFromFunctionA: { input: unknown, environment: unknown, result: Result<unknown> } | null = null
+
+    const c = trace<unknown>((context) => { contextFromFunctionA = context })(a)
+
+    assertEquals(await fromSuccess(c)({ id: 1 }), 2)
+    assertEquals(
+      contextFromFunctionA, 
+      { 
+        input: { id: 1 }, 
+        environment: undefined, 
+        result: { 
+          success: true, 
+          errors: [], 
+          inputErrors: [], 
+          environmentErrors: [], 
+          data:2
+        }
+      }
+    )
+  })
+})

src/domain-functions.ts

@@ -299,6 +299,22 @@ function mapError<O>(
   }
 }
 
+function trace<T>(
+  traceFn: (
+    { input, environment, result }: {
+      input: unknown;
+      environment: unknown;
+      result: Result<T>;
+    },
+  ) => void,
+): (fn: DomainFunction<T>) => DomainFunction<T> {
+  return (fn) => async (input, environment) => {
+    const result = await fn(input, environment);
+    traceFn({ input, environment, result });
+    return result;
+  };
+}
+
 export {
   all,
   first,
@@ -309,4 +325,5 @@ export {
   merge,
   pipe,
   sequence,
+  trace,
 }