@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/createJourneyObservations.js

@@ -0,0 +1,80 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+import { normaliseBlockId } from '@lowdefy/node-utils';
+
+// What a journey's pages reported from inside: the Lowdefy events that
+// completed (the engine's trace hook) and the blocks that were ever visible.
+// Fed by every actor's page through the __lowdefyJourneyObserve binding
+// (client/journeyObserver) and by the runner's own sample at each step's
+// settle. Messages come from page JavaScript, so a malformed one is dropped
+// rather than trusted.
+function createJourneyObservations() {
+  const events = new Map();
+  const rendered = new Map();
+
+  function addEvent({ scope, pageId, blockId, eventName, actionIds }) {
+    if (![scope, pageId, blockId, eventName].every((value) => type.isString(value))) {
+      return;
+    }
+    const event = {
+      scope,
+      pageId,
+      blockId: normaliseBlockId(blockId),
+      eventName,
+      actionIds: type.isArray(actionIds) ? actionIds.filter((id) => type.isString(id)) : [],
+    };
+    events.set(JSON.stringify(event), event);
+  }
+
+  function addRendered({ pageId, blockIds }) {
+    if (!type.isString(pageId) || !type.isArray(blockIds)) {
+      return;
+    }
+    const ids = rendered.get(pageId) ?? new Set();
+    blockIds
+      .filter((blockId) => type.isString(blockId))
+      .forEach((blockId) => ids.add(normaliseBlockId(blockId)));
+    rendered.set(pageId, ids);
+  }
+
+  function receive(message) {
+    if (!type.isObject(message)) {
+      return;
+    }
+    if (message.kind === 'event') {
+      addEvent(message);
+      return;
+    }
+    if (message.kind === 'rendered') {
+      addRendered(message);
+    }
+  }
+
+  function snapshot() {
+    return {
+      events: [...events.values()],
+      rendered: Object.fromEntries(
+        [...rendered.entries()].map(([pageId, ids]) => [pageId, [...ids].sort()])
+      ),
+    };
+  }
+
+  return { receive, snapshot };
+}
+
+export default createJourneyObservations;

package/lib/docs/createLeftOriginError.js

@@ -0,0 +1,26 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import JourneyStepError from './JourneyStepError.js';
+
+function createLeftOriginError({ origin, departure }) {
+  return new JourneyStepError(
+    `Journey left its origin ${origin} for ${departure}; a data set journey must stay on one host of the dev server.`,
+    { expected: `every request to stay on ${origin}`, actual: departure }
+  );
+}
+
+export default createLeftOriginError;

package/lib/docs/createNetworkCounter.js

@@ -0,0 +1,101 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import matchJourneyRoute from './matchJourneyRoute.js';
+import nextJourneySequence from './nextJourneySequence.js';
+
+function requestKey({ pageId, requestId }) {
+  return JSON.stringify([pageId, requestId]);
+}
+
+// Counts what one journey actor's browser context asked the dev server for.
+// It lives in Node and is fed by Playwright's context-level request event, so
+// the counts survive full page loads, which replace everything in the page.
+function createNetworkCounter({ origin, basePath }) {
+  const pagePaths = new Set();
+  const requests = new Map();
+  const endpoints = new Map();
+  // Where the latest call to each request started in nextJourneySequence's
+  // order, kept apart from the counts so a snapshot carries only the counts.
+  const lastStarted = new Map();
+  let appEvents = false;
+
+  function record(request) {
+    const match = matchJourneyRoute({
+      url: request.url(),
+      method: request.method(),
+      origin,
+      basePath,
+    });
+    if (match === null) {
+      return;
+    }
+    switch (match.route) {
+      case 'root':
+        appEvents = true;
+        return;
+      case 'page':
+        pagePaths.add(match.path);
+        return;
+      case 'request': {
+        const key = requestKey(match);
+        const entry = requests.get(key) ?? {
+          pageId: match.pageId,
+          requestId: match.requestId,
+          calls: 0,
+        };
+        entry.calls += 1;
+        requests.set(key, entry);
+        lastStarted.set(key, nextJourneySequence());
+        return;
+      }
+      case 'endpoint':
+        endpoints.set(match.endpointId, (endpoints.get(match.endpointId) ?? 0) + 1);
+        return;
+      default:
+        return;
+    }
+  }
+
+  function countCalls({ request, pageId, endpoint }) {
+    if (!type.isUndefined(endpoint)) {
+      return endpoints.get(endpoint) ?? 0;
+    }
+    return requests.get(requestKey({ pageId, requestId: request }))?.calls ?? 0;
+  }
+
+  // Whether a call to the request started after `since` (a
+  // nextJourneySequence value): wait.request proves a call the step's
+  // interaction caused, not one the page made before it.
+  function calledSince({ request, pageId, since }) {
+    return (lastStarted.get(requestKey({ pageId, requestId: request })) ?? 0) > since;
+  }
+
+  function snapshot() {
+    return {
+      pagePaths: [...pagePaths],
+      appEvents,
+      requests: [...requests.values()].map((entry) => ({ ...entry })),
+      endpoints: [...endpoints.entries()].map(([endpointId, calls]) => ({ endpointId, calls })),
+    };
+  }
+
+  return { record, countCalls, calledSince, snapshot };
+}
+
+export default createNetworkCounter;

package/lib/docs/dataSets/checkSharedCollectionIds.js

@@ -0,0 +1,67 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+// `label` names where a document comes from in a message: "fixture " or "generate.".
+function addIds({ held, connectionId, collection, documents, label }) {
+  held[collection] = held[collection] ?? new Map();
+  documents.forEach((document, index) => {
+    if (type.isUndefined(document._id)) return;
+    held[collection].set(JSON.stringify(document._id), {
+      connectionId,
+      where: `${label}${connectionId}[${index}]`,
+    });
+  });
+}
+
+// parseDataSet refuses a generated _id that is also a fixture's or generated twice, within one
+// connection. Two connections can name one collection, and the store loads them into it together,
+// where a fixture would silently replace a generated document with its _id. This refuses the same
+// collisions across connections, which only the dev build's collection map can see.
+function checkSharedCollectionIds({ dataSetName, dataSet }) {
+  const held = {};
+  Object.entries(dataSet.fixtures).forEach(([connectionId, documents]) => {
+    addIds({
+      held,
+      connectionId,
+      collection: dataSet.collections[connectionId],
+      documents,
+      label: 'fixture ',
+    });
+  });
+  Object.entries(dataSet.generated).forEach(([connectionId, documents]) => {
+    const collection = dataSet.collections[connectionId];
+    const ids = held[collection] ?? new Map();
+    documents.forEach((document, index) => {
+      const key = JSON.stringify(document._id);
+      const holder = ids.get(key);
+      if (type.isUndefined(holder) || holder.connectionId === connectionId) return;
+      throw new Error(
+        `Data set "${dataSetName}" generate.${connectionId}[${index}] _id ${key} is also the _id of ${holder.where}; connections "${connectionId}" and "${holder.connectionId}" both load collection "${collection}".`
+      );
+    });
+    addIds({
+      held,
+      connectionId,
+      collection,
+      documents,
+      label: 'generate.',
+    });
+  });
+}
+
+export default checkSharedCollectionIds;

package/lib/docs/dataSets/dataSessionRegistry.js

@@ -0,0 +1,25 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// The data sessions this dev server process holds, keyed by session id. On globalThis because the
+// journey route that opens a session and the API context that reads it may load as separate module
+// instances in one process (Vite's SSR module graph and Node's), like the journey actor token.
+const REGISTRY_KEY = Symbol.for('lowdefy.devServer.dataSessions');
+globalThis[REGISTRY_KEY] ??= new Map();
+
+const dataSessionRegistry = globalThis[REGISTRY_KEY];
+
+export default dataSessionRegistry;