Merge pull request #68 from mkantor/serializable-runtime-context

mkantor · web-flow · commit 884904bc18fb · 2025-05-16T14:23:33.000-04:00
Make runtime context functions serializable
diff --git a/src/language/runtime/keywords.ts b/src/language/runtime/keywords.ts
@@ -1,127 +1,145 @@
 import either from '@matt.kantor/either'
-import option from '@matt.kantor/option'
+import option, { type Option } from '@matt.kantor/option'
 import { parseArgs } from 'node:util'
 import { writeOutput } from '../cli/output.js'
 import { keywordHandlers as compilerKeywordHandlers } from '../compiling.js'
 import {
   isFunctionNode,
+  keyPathToLookupExpression,
   makeFunctionNode,
   makeObjectNode,
   readRuntimeExpression,
   serialize,
   types,
   type KeywordHandlers,
 } from '../semantics.js'
+import type { NonEmptyKeyPath } from '../semantics/key-path.js'
 import { prettyJson } from '../unparsing.js'
 
-const unserializableFunction = () =>
-  either.makeLeft({
-    kind: 'unserializableValue',
-    message: 'this function cannot be serialized',
-  })
+const serializeFunction =
+  (runtimeFunctionParameterName: Option<string>) =>
+  (keyPath: NonEmptyKeyPath) => {
+    const serialize = either.map(
+      option.match(runtimeFunctionParameterName, {
+        none: _ =>
+          either.makeLeft({
+            kind: 'unserializableValue',
+            message: 'the runtime function cannot be serialized',
+          }),
+        some: either.makeRight,
+      }),
+      parameterName => keyPathToLookupExpression([parameterName, ...keyPath]),
+    )
+    return () => serialize
+  }
 
-const runtimeContext = makeObjectNode({
-  arguments: makeObjectNode({
-    lookup: makeFunctionNode(
-      {
-        parameter: types.atom,
-        return: types.option(types.atom),
-      },
-      unserializableFunction,
-      option.none,
-      key => {
-        if (typeof key !== 'string') {
-          return either.makeLeft({
-            kind: 'panic',
-            message: 'key was not an atom',
-          })
-        } else {
-          const { values: argumentValues } = parseArgs({
-            args: process.argv,
-            strict: false,
-            options: {
-              [key]: { type: 'string' },
-            },
-          })
-          const argument = argumentValues[key]
-          if (typeof argument !== 'string') {
-            return either.makeRight(
-              makeObjectNode({
-                tag: 'none',
-                value: makeObjectNode({}),
-              }),
-            )
+const runtimeContext = (runtimeFunctionParameterName: Option<string>) => {
+  const serializeRuntimeContextFunction = serializeFunction(
+    runtimeFunctionParameterName,
+  )
+  return makeObjectNode({
+    arguments: makeObjectNode({
+      lookup: makeFunctionNode(
+        {
+          parameter: types.atom,
+          return: types.option(types.atom),
+        },
+        serializeRuntimeContextFunction(['arguments', 'lookup']),
+        option.none,
+        key => {
+          if (typeof key !== 'string') {
+            return either.makeLeft({
+              kind: 'panic',
+              message: 'key was not an atom',
+            })
           } else {
-            return either.makeRight(
-              makeObjectNode({
-                tag: 'some',
-                value: argument,
-              }),
-            )
+            const { values: argumentValues } = parseArgs({
+              args: process.argv,
+              strict: false,
+              options: {
+                [key]: { type: 'string' },
+              },
+            })
+            const argument = argumentValues[key]
+            if (typeof argument !== 'string') {
+              return either.makeRight(
+                makeObjectNode({
+                  tag: 'none',
+                  value: makeObjectNode({}),
+                }),
+              )
+            } else {
+              return either.makeRight(
+                makeObjectNode({
+                  tag: 'some',
+                  value: argument,
+                }),
+              )
+            }
           }
-        }
-      },
-    ),
-  }),
-  environment: makeObjectNode({
-    lookup: makeFunctionNode(
+        },
+      ),
+    }),
+    environment: makeObjectNode({
+      lookup: makeFunctionNode(
+        {
+          parameter: types.atom,
+          return: types.option(types.atom),
+        },
+        serializeRuntimeContextFunction(['environment', 'lookup']),
+        option.none,
+        key => {
+          if (typeof key !== 'string') {
+            return either.makeLeft({
+              kind: 'panic',
+              message: 'key was not an atom',
+            })
+          } else {
+            const environmentVariable = process.env[key]
+            if (environmentVariable === undefined) {
+              return either.makeRight(
+                makeObjectNode({
+                  tag: 'none',
+                  value: makeObjectNode({}),
+                }),
+              )
+            } else {
+              return either.makeRight(
+                makeObjectNode({
+                  tag: 'some',
+                  value: environmentVariable,
+                }),
+              )
+            }
+          }
+        },
+      ),
+    }),
+    log: makeFunctionNode(
       {
-        parameter: types.atom,
-        return: types.option(types.atom),
+        parameter: types.something,
+        return: types.object,
       },
-      unserializableFunction,
+      serializeRuntimeContextFunction(['log']),
       option.none,
-      key => {
-        if (typeof key !== 'string') {
+      output => {
+        const serializationResult = serialize(output)
+        if (either.isLeft(serializationResult)) {
           return either.makeLeft({
             kind: 'panic',
-            message: 'key was not an atom',
+            message: serializationResult.value.message,
           })
         } else {
-          const environmentVariable = process.env[key]
-          if (environmentVariable === undefined) {
-            return either.makeRight(
-              makeObjectNode({
-                tag: 'none',
-                value: makeObjectNode({}),
-              }),
-            )
-          } else {
-            return either.makeRight(
-              makeObjectNode({
-                tag: 'some',
-                value: environmentVariable,
-              }),
-            )
-          }
+          writeOutput(process.stderr, prettyJson, serializationResult.value)
+          return either.makeRight(output)
         }
       },
     ),
-  }),
-  log: makeFunctionNode(
-    {
-      parameter: types.something,
-      return: types.object,
-    },
-    unserializableFunction,
-    option.none,
-    output => {
-      const serializationResult = serialize(output)
-      if (either.isLeft(serializationResult)) {
-        return either.makeLeft({
-          kind: 'panic',
-          message: serializationResult.value.message,
-        })
-      } else {
-        writeOutput(process.stderr, prettyJson, serializationResult.value)
-        return either.makeRight(output)
-      }
-    },
-  ),
-  program: makeObjectNode({
-    start_time: new Date().toISOString(),
-  }),
-})
+    program: makeObjectNode({
+      start_time: new Date().toISOString(),
+    }),
+  })
+}
 
 export const keywordHandlers: KeywordHandlers = {
   ...compilerKeywordHandlers,
@@ -139,7 +157,9 @@ export const keywordHandlers: KeywordHandlers = {
               'a function must be provided via the property `function` or `0`',
           })
         } else {
-          const result = runtimeFunction(runtimeContext)
+          const result = runtimeFunction(
+            runtimeContext(runtimeFunction.parameterName),
+          )
           if (either.isLeft(result)) {
             // The runtime function panicked or had an unavailable dependency (which results in a panic
             // anyway in this context).
diff --git a/src/language/semantics.ts b/src/language/semantics.ts
@@ -35,6 +35,7 @@ export {
   type IndexExpression,
 } from './semantics/expressions/index-expression.js'
 export {
+  keyPathToLookupExpression,
   makeLookupExpression,
   readLookupExpression,
   type LookupExpression,
diff --git a/src/language/semantics/expressions/lookup-expression.ts b/src/language/semantics/expressions/lookup-expression.ts
@@ -2,6 +2,7 @@ import either, { type Either } from '@matt.kantor/either'
 import type { ElaborationError } from '../../errors.js'
 import type { Atom, Molecule } from '../../parsing.js'
 import { isExpressionWithArgument } from '../expression.js'
+import { keyPathToMolecule, type NonEmptyKeyPath } from '../key-path.js'
 import { makeObjectNode, type ObjectNode } from '../object-node.js'
 import {
   stringifySemanticGraphForEndUser,
@@ -11,6 +12,7 @@ import {
   asSemanticGraph,
   readArgumentsFromExpression,
 } from './expression-utilities.js'
+import { makeIndexExpression } from './index-expression.js'
 
 export type LookupExpression = ObjectNode & {
   readonly 0: '@lookup'
@@ -45,3 +47,16 @@ export const makeLookupExpression = (key: Atom): LookupExpression =>
     0: '@lookup',
     1: makeObjectNode({ key }),
   })
+
+export const keyPathToLookupExpression = (keyPath: NonEmptyKeyPath) => {
+  const [initialKey, ...indexes] = keyPath
+  const initialLookup = makeLookupExpression(initialKey)
+  if (indexes.length === 0) {
+    return initialLookup
+  } else {
+    return makeIndexExpression({
+      object: initialLookup,
+      query: keyPathToMolecule(indexes),
+    })
+  }
+}
diff --git a/src/language/semantics/key-path.ts b/src/language/semantics/key-path.ts
@@ -5,6 +5,7 @@ import { inlinePlz, unparse } from '../unparsing.js'
 import type { ObjectNode } from './object-node.js'
 
 export type KeyPath = readonly Atom[]
+export type NonEmptyKeyPath = readonly [Atom, ...KeyPath]
 
 export const stringifyKeyPathForEndUser = (keyPath: KeyPath): string =>
   either.match(unparse(keyPathToMolecule(keyPath), inlinePlz), {
diff --git a/src/language/semantics/stdlib/stdlib-utilities.ts b/src/language/semantics/stdlib/stdlib-utilities.ts
@@ -1,14 +1,12 @@
 import either, { type Either } from '@matt.kantor/either'
 import option from '@matt.kantor/option'
 import type { DependencyUnavailable, Panic } from '../../errors.js'
-import type { Atom } from '../../parsing.js'
 import {
+  keyPathToLookupExpression,
   makeApplyExpression,
-  makeIndexExpression,
-  makeLookupExpression,
 } from '../../semantics.js'
 import { makeFunctionNode } from '../function-node.js'
-import { keyPathToMolecule, type KeyPath } from '../key-path.js'
+import { type NonEmptyKeyPath } from '../key-path.js'
 import {
   containsAnyUnelaboratedNodes,
   type SemanticGraph,
@@ -34,21 +32,6 @@ const handleUnavailableDependencies =
     }
   }
 
-type NonEmptyKeyPath = readonly [Atom, ...KeyPath]
-
-const keyPathToLookupExpression = (keyPath: NonEmptyKeyPath) => {
-  const [initialKey, ...indexes] = keyPath
-  const initialLookup = makeLookupExpression(initialKey)
-  if (indexes.length === 0) {
-    return initialLookup
-  } else {
-    return makeIndexExpression({
-      object: initialLookup,
-      query: keyPathToMolecule(indexes),
-    })
-  }
-}
-
 export const serializeOnceAppliedFunction =
   (keyPath: NonEmptyKeyPath, argument: SemanticGraph) => () =>
     either.makeRight(
