Merge branch 'DouglasNeuroInformatics:main' into improve-error-desc

Author: david-roper

.gitignore

@@ -62,3 +62,6 @@ apps/outreach/src/content/docs/en/runtime-core-docs/
 # docker dbs
 mongo/
 sqlite/
+
+# runtime core intermediate build
+packages/runtime-core/lib/

.nvmrc

@@ -1 +1 @@
-lts/iron
+lts/jod

apps/api/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:iron AS base
+FROM node:lts-jod AS base
 WORKDIR /app
 ARG RELEASE_VERSION
 ENV GATEWAY_DATABASE_URL="file:/dev/null"

apps/gateway/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:iron AS base
+FROM node:lts-jod AS base
 WORKDIR /app
 ARG RELEASE_VERSION
 ENV GATEWAY_DATABASE_URL=file:/app/sqlite/gateway.db

apps/outreach/astro.config.ts

@@ -62,7 +62,7 @@ export default defineConfig({
       },
       plugins: [
         starlightTypeDocPlugin({
-          entryPoints: [path.resolve(runtimeCoreRoot, 'src/index.d.ts')],
+          entryPoints: [path.resolve(runtimeCoreRoot, 'lib/index.d.ts')],
           locale: 'en',
           output: 'runtime-core-docs',
           sidebar: {

apps/web/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:iron AS base
+FROM node:lts-jod AS base
 ARG RELEASE_VERSION
 WORKDIR /app
 ENV PNPM_HOME="/pnpm"

docs/en/4-concepts/4.3-runtime-execution-context.md

@@ -0,0 +1,71 @@
+---
+title: Runtime Execution Context
+slug: en/docs/concepts/runtime-execution-context
+sidebar:
+  order: 3
+---
+
+In JavaScript, the global object varies depending on the execution environment. In the browser, the global object is `window`, which includes properties like `document`. In Node.js, the global object is `global`. This object is specific to Node.js and is not available in browsers.
+
+For example, you cannot access `process.env` in a browser environment because it is specific to Node.js. Similarly, calling `document.createElement` on a server does not work, as it is intended for the client-side. Attempting either will result in a runtime error.
+
+In Open Data Capture, code runs on both the client and server. You should therefore not access browser-specific APIs, like `document` or `window` unless you are within functions named `render`, which execute exclusively on the client. For those familiar with Next.js, think of these functions as rendering a component with a "use client" directive within a React Server Component.
+
+## Example of Problematic Instrument
+
+```ts
+import { defineInstrument } from '/runtime/v1/@opendatacapture/runtime-core';
+import { z } from '/runtime/v1/zod@3.23.x';
+
+const button = document.createElement('button');
+button.textContent = 'Submit Instrument';
+document.body.appendChild(button);
+
+export default defineInstrument({
+  // ...
+  kind: 'INTERACTIVE',
+  content: {
+    render(done) {
+      button.addEventListener('click', () => {
+        done({ message: 'Hello World' });
+      });
+    }
+  }
+  // ...
+});
+```
+
+## Fixing This Instrument
+
+To fix the instrument, there are two options:
+
+1. Move the browser-specific code directly within the render function
+2. Wrap the browser-specific code in a function. This function can be defined outside the render function but must only be called within it.
+
+**Example**
+
+```ts
+import { defineInstrument } from '/runtime/v1/@opendatacapture/runtime-core';
+import { z } from '/runtime/v1/zod@3.23.x';
+
+function createButton() {
+  const button = document.createElement('button');
+  button.textContent = 'Submit Instrument';
+  document.body.appendChild(button);
+  return button;
+}
+
+export default defineInstrument({
+  // ...
+  kind: 'INTERACTIVE',
+  content: {
+    render(done) {
+      const button = createButton();
+      button.addEventListener('click', () => {
+        done({ message: 'Hello World' });
+      });
+    }
+  }
+  // ...
+});
+```

package.json

@@ -1,12 +1,12 @@
 {
   "name": "opendatacapture",
   "type": "module",
-  "version": "1.8.5",
+  "version": "1.8.6",
   "private": true,
   "packageManager": "pnpm@9.15.4",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=v20.17.0"
+    "node": ">=v22.11.0"
   },
   "scripts": {
     "build": "env-cmd turbo run build",
@@ -53,7 +53,7 @@
     "@swc/helpers": "^0.5.15",
     "@types/github-script": "https://github.com/actions/github-script/archive/refs/tags/v7.0.1.tar.gz",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^20.14.2",
+    "@types/node": "22.x",
     "@vitest/browser": "^2.0.5",
     "@vitest/coverage-v8": "^2.0.5",
     "dotenv": "^16.4.7",

packages/instrument-bundler/src/__tests__/repositories/interactive/index.tsx

@@ -2,6 +2,8 @@ import { defineInstrument } from '/runtime/v1/@opendatacapture/runtime-core';
 import { createRoot } from '/runtime/v1/react-dom@18.x/client';
 import { z } from '/runtime/v1/zod@3.23.x';
 
+const { sum } = await import('/runtime/v1/lodash-es@4.x');
+
 import './styles.css';
 import '/runtime/v1/normalize.css@8.x/normalize.css';
 
@@ -18,7 +20,7 @@ export default defineInstrument({
       root.render(
         <div>
           <h1>Interactive Task</h1>
-          <button onClick={() => done({})}>Done</button>
+          <button onClick={() => done({ value: sum([1, 2, 3]) })}>Done</button>
         </div>
       );
     }

packages/instrument-bundler/src/__tests__/transform.test.ts

@@ -4,24 +4,24 @@ import { transformImports } from '../transform.js';
 
 describe('transformImports', () => {
   it('should transform a default import', () => {
-    expect(transformImports("import React from 'react';")).toBe("const { default: React } = await import('react');");
+    expect(transformImports("import React from 'react';")).toBe("const { default: React } = await __import('react');");
   });
   it('should transform named imports', () => {
     expect(transformImports("import { useEffect, useState } from 'react';")).toBe(
-      "const { useEffect, useState } = await import('react');"
+      "const { useEffect, useState } = await __import('react');"
     );
   });
   it('should transform named and default imports from the same source', () => {
     expect(transformImports("import React, { useState } from 'react';")).toBe(
-      "const { useState, default: React } = await import('react');"
+      "const { useState, default: React } = await __import('react');"
     );
   });
   it('should transform a namespace import', () => {
-    expect(transformImports("import * as React from 'react';")).toBe("const React = await import('react');");
+    expect(transformImports("import * as React from 'react';")).toBe("const React = await __import('react');");
   });
   it('should transform named and default imports from the same source', () => {
     expect(transformImports("import _ from 'lodash'; import { useEffect, useState } from 'react';")).toBe(
-      "const { default: _ } = await import('lodash'); const { useEffect, useState } = await import('react');"
+      "const { default: _ } = await __import('lodash'); const { useEffect, useState } = await __import('react');"
     );
   });
 });