@lowdefy/server-dev 6.1.0 → 7.1.0

package/lib/docs/dataSets/readDataSession.js

@@ -0,0 +1,41 @@
+/*
+  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 dataSessionRegistry from './dataSessionRegistry.js';
+import { JOURNEY_COOKIES, readJourneyCookie } from '../../server/journeyCookies.js';
+
+// The data session a request's lowdefy_journey_data cookie names:
+// - null when there is no cookie or its token is not this process's: not a journey's request, so it
+//   reads the app's own database like any other;
+// - the session while it is open or closing;
+// - { ended: id } when the token verifies but the session is not open (closed, or never opened). A
+//   verified token proves the request came from a journey, so the caller refuses it rather than let
+//   it fall back to the real database.
+function readDataSession(cookieHeader) {
+  const id = readJourneyCookie({ cookieHeader, name: JOURNEY_COOKIES.data.name });
+  if (type.isNone(id)) {
+    return null;
+  }
+  const session = dataSessionRegistry.get(id);
+  if (type.isNone(session) || (session.state !== 'open' && session.state !== 'closing')) {
+    return { ended: id };
+  }
+  return session;
+}
+
+export default readDataSession;

package/lib/docs/dataSets/readDataSession.test.mjs

@@ -0,0 +1,57 @@
+/*
+  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 dataSessionRegistry from './dataSessionRegistry.js';
+import readDataSession from './readDataSession.js';
+import { journeyActorToken } from '../../server/auth/journeyActor.js';
+
+afterEach(() => {
+  dataSessionRegistry.clear();
+});
+
+function register(state) {
+  const session = { id: 'abc', state, work: new Set() };
+  dataSessionRegistry.set('abc', session);
+  return session;
+}
+
+test('readDataSession returns null without a data cookie', () => {
+  register('open');
+  expect(readDataSession(undefined)).toBeNull();
+  expect(readDataSession('other=1')).toBeNull();
+});
+
+test('readDataSession returns null for a cookie with the wrong token', () => {
+  register('open');
+  expect(readDataSession('lowdefy_journey_data=forged.abc')).toBeNull();
+});
+
+test('readDataSession returns an open or closing session for a verified cookie', () => {
+  const session = register('open');
+  expect(readDataSession(`a=1; lowdefy_journey_data=${journeyActorToken}.abc`)).toBe(session);
+  session.state = 'closing';
+  expect(readDataSession(`lowdefy_journey_data=${journeyActorToken}.abc`)).toBe(session);
+});
+
+test('readDataSession returns { ended } for a verified cookie naming an unknown or still loading session', () => {
+  expect(readDataSession(`lowdefy_journey_data=${journeyActorToken}.gone`)).toEqual({
+    ended: 'gone',
+  });
+  register('loading');
+  expect(readDataSession(`lowdefy_journey_data=${journeyActorToken}.abc`)).toEqual({
+    ended: 'abc',
+  });
+});

package/lib/docs/dataSets/readDataSet.js

@@ -0,0 +1,83 @@
+/*
+  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 { parseDataSet } from '@lowdefy/node-utils';
+
+import checkSharedCollectionIds from './checkSharedCollectionIds.js';
+import describeTargetKey from './describeTargetKey.js';
+import readConnectionArtifacts from './readConnectionArtifacts.js';
+import resolveDataSetCollection from './resolveDataSetCollection.js';
+
+function getKeyedConnectionIds({ dataSet }) {
+  return [
+    ...new Set([
+      ...Object.keys(dataSet.fixtures),
+      ...Object.keys(dataSet.generated),
+      ...Object.keys(dataSet.indexes),
+    ]),
+  ];
+}
+
+// Sorts a URI's default database (no databaseName) before its named ones.
+function sortKey(key) {
+  const [uri, databaseName] = JSON.parse(key);
+  return [uri, databaseName ?? ''].join('\u0000');
+}
+
+// Every database target the built connections name, sorted, so each run numbers them alike and the
+// first one (the database a computed target reads) is the same on every run.
+function listDatabaseTargets({ artifacts }) {
+  const keys = new Set();
+  Object.values(artifacts).forEach((artifact) => {
+    const key = describeTargetKey({ properties: artifact.properties });
+    if (!type.isNone(key)) keys.add(key);
+  });
+  return [...keys].sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+}
+
+// The data set checks only the dev build can make, on top of parseDataSet's: every connection the
+// data set names is a MongoDBCollection with a literal collection, and a generated _id that another
+// connection on the same collection in the same database target also holds is refused. Adds the
+// database target of each connection it names (targets) and of every connection in the build
+// (databaseTargets): a data session gives each target a database of its own. Runs before any
+// browser opens.
+async function readDataSet({ configDirectory, buildDirectory, name }) {
+  const dataSet = await parseDataSet({ configDirectory, name });
+  const artifacts = await readConnectionArtifacts({ buildDirectory });
+  const keyedIds = getKeyedConnectionIds({ dataSet });
+  const databaseTargets = listDatabaseTargets({ artifacts });
+  const collections = {};
+  const targets = {};
+  keyedIds.forEach((connectionId) => {
+    const artifact = artifacts[connectionId];
+    collections[connectionId] = resolveDataSetCollection({
+      dataSetName: name,
+      connectionId,
+      artifact,
+    }).collection;
+    // A target computed per request reads the session's first database, the first target's, so it
+    // groups and checks _ids with that target's connections.
+    targets[connectionId] =
+      describeTargetKey({ properties: artifact.properties }) ?? databaseTargets[0] ?? null;
+  });
+
+  checkSharedCollectionIds({ dataSetName: name, dataSet: { ...dataSet, collections, targets } });
+
+  return { ...dataSet, collections, targets, databaseTargets };
+}
+
+export default readDataSet;

package/lib/docs/dataSets/readDataSet.test.mjs

@@ -0,0 +1,251 @@
+/*
+  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 fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import readDataSet from './readDataSet.js';
+
+let configDirectory;
+let buildDirectory;
+
+beforeEach(() => {
+  configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-read-data-set-'));
+  buildDirectory = path.join(configDirectory, '.lowdefy', 'dev', 'build');
+  fs.mkdirSync(path.join(configDirectory, 'tests', 'data'), { recursive: true });
+  fs.mkdirSync(path.join(buildDirectory, 'connections'), { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+});
+
+function writeDataSet(name, content) {
+  fs.writeFileSync(path.join(configDirectory, 'tests', 'data', `${name}.yaml`), content);
+}
+
+function writeConnection(connectionId, artifact) {
+  const filePath = path.join(buildDirectory, 'connections', `${connectionId}.json`);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(
+    filePath,
+    JSON.stringify({ connectionId, '~k': `k_${connectionId}`, ...artifact })
+  );
+}
+
+function mongo(properties) {
+  return {
+    type: 'MongoDBCollection',
+    properties: { databaseUri: { _secret: 'MONGODB_URI', '~k': 'k' }, ...properties },
+  };
+}
+
+test('readDataSet maps each keyed connection to its collection', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets' }));
+  writeConnection('tickets-archive', mongo({ collection: 'tickets' }));
+  writeConnection('organizations', mongo({ collection: 'orgs', databaseName: 'app' }));
+  writeConnection('api', { type: 'AxiosHttp', properties: { baseURL: 'https://example.com' } });
+  writeDataSet(
+    'fixtures-only',
+    `fixtures:
+  tickets: [{ _id: t1 }]
+  tickets-archive: [{ _id: t2 }]
+indexes:
+  organizations: [{ key: { name: 1 } }]
+users:
+  owner: { id: u_1 }
+`
+  );
+  const dataSet = await readDataSet({ configDirectory, buildDirectory, name: 'fixtures-only' });
+  expect(dataSet.collections).toEqual({
+    tickets: 'tickets',
+    'tickets-archive': 'tickets',
+    organizations: 'orgs',
+  });
+  expect(dataSet.warnings).toEqual([]);
+  expect(dataSet.users).toEqual({ owner: { id: 'u_1' } });
+});
+
+test('readDataSet reads module connections, which the build writes under their module folder', async () => {
+  writeConnection('contacts/contacts', mongo({ collection: 'contacts' }));
+  writeConnection('crm-contacts', mongo({ collection: 'contacts', databaseName: 'crm' }));
+  writeDataSet('alpha', 'fixtures:\n  contacts/contacts: [{ _id: c1 }]\n');
+  const dataSet = await readDataSet({ configDirectory, buildDirectory, name: 'alpha' });
+  expect(dataSet.databaseTargets).toEqual([
+    JSON.stringify(['secret:MONGODB_URI', null]),
+    JSON.stringify(['secret:MONGODB_URI', 'crm']),
+  ]);
+});
+
+test('readDataSet maps a module connection to its collection', async () => {
+  writeConnection('contacts/contacts', mongo({ collection: 'contacts' }));
+  writeDataSet('alpha', 'fixtures:\n  contacts/contacts: [{ _id: c1 }]\n');
+  const dataSet = await readDataSet({ configDirectory, buildDirectory, name: 'alpha' });
+  expect(dataSet.collections).toEqual({ 'contacts/contacts': 'contacts' });
+});
+
+test('readDataSet refuses a fixture keyed by a non-MongoDB connection', async () => {
+  writeConnection('api', { type: 'AxiosHttp', properties: { baseURL: 'https://example.com' } });
+  writeDataSet('alpha', 'fixtures:\n  api: [{ _id: a }]\n');
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Data set "alpha" connection "api" is a AxiosHttp connection; data sets load MongoDBCollection connections only.'
+  );
+});
+
+test('readDataSet refuses a key that is not a connection', async () => {
+  writeDataSet('alpha', 'fixtures:\n  missing: [{ _id: a }]\n');
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Data set "alpha" connection "missing" is not a connection in this app.'
+  );
+});
+
+test('readDataSet refuses an index keyed by a connection whose collection is an operator', async () => {
+  writeConnection('tickets', mongo({ collection: { _user: 'organizationId' } }));
+  writeDataSet('alpha', 'indexes:\n  tickets: [{ key: { a: 1 } }]\n');
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Data set "alpha" connection "tickets" has a computed "collection"'
+  );
+});
+
+test('readDataSet refuses an indexed connection whose databaseName is an operator', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets', databaseName: { _env: 'DB' } }));
+  writeDataSet('alpha', 'indexes:\n  tickets:\n    - { key: { number: 1 } }\n');
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Data set "alpha" connection "tickets" has a computed "databaseName"'
+  );
+});
+
+test('readDataSet maps each keyed connection to its database target', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets' }));
+  writeConnection('legacy-tickets', mongo({ collection: 'tickets', databaseName: 'legacy' }));
+  writeConnection('reporting', {
+    type: 'MongoDBCollection',
+    properties: { databaseUri: { _secret: 'REPORTING_URI' }, collection: 'tickets' },
+  });
+  writeConnection('computed', {
+    type: 'MongoDBCollection',
+    properties: { databaseUri: { _env: 'URI' }, collection: 'tickets' },
+  });
+  writeConnection('api', { type: 'AxiosHttp', properties: { baseURL: 'https://example.com' } });
+  writeDataSet(
+    'alpha',
+    'fixtures:\n  tickets: [{ _id: a }]\n  legacy-tickets: [{ _id: a }]\n  reporting: [{ _id: a }]\n  computed: [{ _id: b }]\n'
+  );
+  const dataSet = await readDataSet({ configDirectory, buildDirectory, name: 'alpha' });
+  expect(dataSet.targets).toEqual({
+    tickets: JSON.stringify(['secret:MONGODB_URI', null]),
+    'legacy-tickets': JSON.stringify(['secret:MONGODB_URI', 'legacy']),
+    reporting: JSON.stringify(['secret:REPORTING_URI', null]),
+    // Computed per request: the first target's, the database it reads.
+    computed: JSON.stringify(['secret:MONGODB_URI', null]),
+  });
+  // Every target in the build, sorted, whether or not the data set names it.
+  expect(dataSet.databaseTargets).toEqual([
+    JSON.stringify(['secret:MONGODB_URI', null]),
+    JSON.stringify(['secret:MONGODB_URI', 'legacy']),
+    JSON.stringify(['secret:REPORTING_URI', null]),
+  ]);
+  expect(dataSet.warnings).toEqual([]);
+});
+
+test('readDataSet accepts one _id generated on one collection in two database targets', async () => {
+  writeConnection('users', mongo({ collection: 'users' }));
+  writeConnection('auth-users', {
+    type: 'MongoDBCollection',
+    properties: { databaseUri: { _secret: 'AUTH_URI' }, collection: 'users' },
+  });
+  writeDataSet(
+    'alpha',
+    'fixtures:\n  auth-users: [{ _id: users-1 }]\ngenerate:\n  seed: 1\n  users:\n    count: 1\n'
+  );
+  const dataSet = await readDataSet({ configDirectory, buildDirectory, name: 'alpha' });
+  expect(dataSet.collections).toEqual({ users: 'users', 'auth-users': 'users' });
+});
+
+test('readDataSet refuses a generated _id a computed-target connection also holds on the first target', async () => {
+  writeConnection('users', mongo({ collection: 'users' }));
+  writeConnection('computed-users', {
+    type: 'MongoDBCollection',
+    properties: { databaseUri: { _env: 'URI' }, collection: 'users' },
+  });
+  writeDataSet(
+    'alpha',
+    'fixtures:\n  computed-users: [{ _id: users-1 }]\ngenerate:\n  seed: 1\n  users:\n    count: 1\n'
+  );
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'connections "users" and "computed-users" both load collection "users".'
+  );
+});
+
+test('readDataSet resolves generated connections and refuses one the app does not have', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets' }));
+  writeDataSet(
+    'alpha',
+    'generate:\n  seed: 1\n  tickets:\n    count: 2\n  invoices:\n    count: 1\n'
+  );
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Data set "alpha" connection "invoices" is not a connection in this app.'
+  );
+  writeDataSet('beta', 'generate:\n  seed: 1\n  tickets:\n    count: 2\n');
+  const dataSet = await readDataSet({ configDirectory, buildDirectory, name: 'beta' });
+  expect(dataSet.collections).toEqual({ tickets: 'tickets' });
+  expect(dataSet.generated.tickets.map(({ _id }) => _id)).toEqual(['tickets-1', 'tickets-2']);
+});
+
+test('readDataSet passes the size advice of a large data set on as a warning', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets' }));
+  writeDataSet('big', 'generate:\n  seed: 1\n  tickets:\n    count: 1200\n');
+  const dataSet = await readDataSet({ configDirectory, buildDirectory, name: 'big' });
+  expect(dataSet.warnings).toEqual([
+    'Data set "big" loads 1,200 documents for connection "tickets". More than 1,000 per collection is not advised: every journey on it loads slower, and journeys target fixture values, not volume.',
+  ]);
+});
+
+test('readDataSet refuses a fixture on another connection of the same collection sharing a generated _id', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets' }));
+  writeConnection('tickets-archive', mongo({ collection: 'tickets' }));
+  writeDataSet(
+    'alpha',
+    'fixtures:\n  tickets-archive: [{ _id: tickets-2 }]\ngenerate:\n  seed: 1\n  tickets:\n    count: 2\n'
+  );
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Data set "alpha" generate.tickets[1] _id "tickets-2" is also the _id of fixture tickets-archive[0]; connections "tickets" and "tickets-archive" both load collection "tickets".'
+  );
+});
+
+test('readDataSet refuses two connections of the same collection generating one _id', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets' }));
+  writeConnection('tickets-archive', mongo({ collection: 'tickets' }));
+  writeDataSet(
+    'alpha',
+    'generate:\n  seed: 1\n  tickets:\n    count: 1\n    fields:\n      _id: { sequence: { prefix: t-, start: 1 } }\n  tickets-archive:\n    count: 1\n    fields:\n      _id: { sequence: { prefix: t-, start: 1 } }\n'
+  );
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Data set "alpha" generate.tickets-archive[0] _id "t-1" is also the _id of generate.tickets[0]; connections "tickets-archive" and "tickets" both load collection "tickets".'
+  );
+});
+
+test('readDataSet accepts the same _id on connections of different collections', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets' }));
+  writeConnection('invoices', mongo({ collection: 'invoices' }));
+  writeDataSet(
+    'alpha',
+    'fixtures:\n  invoices: [{ _id: tickets-1 }]\ngenerate:\n  seed: 1\n  tickets:\n    count: 1\n'
+  );
+  const dataSet = await readDataSet({ configDirectory, buildDirectory, name: 'alpha' });
+  expect(dataSet.generated.tickets.map(({ _id }) => _id)).toEqual(['tickets-1']);
+});

package/lib/docs/dataSets/registerDataStoreShutdown.js

@@ -0,0 +1,47 @@
+/*
+  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 removeDataStoreFiles from './removeDataStoreFiles.js';
+
+const SHUTDOWN_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+
+// A store is stopped, with its temporary database directory removed, when the dev server process
+// shuts down. The manager stops the process with SIGTERM, a terminal Ctrl+C sends SIGINT and closing
+// the terminal sends SIGHUP, whose default action ends the process without an exit event; on each
+// the store stops first and the signal is raised again, so the process ends as it would have.
+// Vite's own SIGTERM handler can exit before that stop finishes, so the exit hook kills mongod and
+// removes its directory synchronously. mongodb-memory-server's killer process still stops mongod
+// after a crash, which runs neither.
+function registerDataStoreShutdown({ replSet, stop }) {
+  async function onSignal(signal) {
+    try {
+      await stop();
+    } finally {
+      process.kill(process.pid, signal);
+    }
+  }
+  function onExit() {
+    removeDataStoreFiles({ replSet });
+  }
+  SHUTDOWN_SIGNALS.forEach((signal) => process.once(signal, onSignal));
+  process.once('exit', onExit);
+  return function unregisterDataStoreShutdown() {
+    SHUTDOWN_SIGNALS.forEach((signal) => process.off(signal, onSignal));
+    process.off('exit', onExit);
+  };
+}
+
+export default registerDataStoreShutdown;

package/lib/docs/dataSets/removeDataStoreFiles.js

@@ -0,0 +1,32 @@
+/*
+  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 fs from 'node:fs';
+
+// Kills each mongod of the store and removes its temporary database directory, synchronously, so
+// it also runs from a process exit hook. A store already stopped with cleanup has no servers left.
+function removeDataStoreFiles({ replSet }) {
+  replSet.servers.forEach((server) => {
+    const info = server.instanceInfo;
+    if (info === undefined) return;
+    info.instance.mongodProcess?.kill('SIGKILL');
+    if (info.tmpDir !== undefined) {
+      fs.rmSync(info.tmpDir, { recursive: true, force: true });
+    }
+  });
+}
+
+export default removeDataStoreFiles;

package/lib/docs/dataSets/resolveDataSetCollection.js

@@ -0,0 +1,46 @@
+/*
+  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';
+
+// A data set loads a connection only when the built artifact names its
+// collection: an operator there is evaluated per request, so the collection cannot be known before
+// one. Returns the literal collection and databaseName (or undefined).
+function resolveDataSetCollection({ dataSetName, connectionId, artifact }) {
+  const where = `Data set "${dataSetName}" connection "${connectionId}"`;
+  if (type.isNone(artifact)) {
+    throw new Error(`${where} is not a connection in this app.`);
+  }
+  if (artifact.type !== 'MongoDBCollection') {
+    throw new Error(
+      `${where} is a ${artifact.type} connection; data sets load MongoDBCollection connections only.`
+    );
+  }
+  const { collection, databaseName } = artifact.properties ?? {};
+  if (!type.isString(collection)) {
+    throw new Error(
+      `${where} has a computed "collection"; a data set can only load a connection whose collection is a literal string.`
+    );
+  }
+  if (!type.isUndefined(databaseName) && !type.isString(databaseName)) {
+    throw new Error(
+      `${where} has a computed "databaseName"; a data set can only load a connection whose databaseName is a literal string or not set.`
+    );
+  }
+  return { collection, databaseName };
+}
+
+export default resolveDataSetCollection;

package/lib/docs/dataSets/resolveJourneyDataSet.js

@@ -0,0 +1,106 @@
+/*
+  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 readDataSet from './readDataSet.js';
+
+function isUserName(user) {
+  return type.isString(user) && user !== 'none';
+}
+
+function describeDeclaredUsers({ users }) {
+  const names = Object.keys(users);
+  if (names.length === 0) {
+    return 'It declares no users.';
+  }
+  return `Declared: ${names.join(', ')}.`;
+}
+
+// Everything a journey's data set decides before a browser opens: the data set itself (read and
+// checked against the built connections), and who the journey acts as. A string `user` other than
+// "none" names a data set user. Returns { dataSet, user } (both undefined for a journey with no data
+// set) or { error }.
+//
+// `user: none` while a dev mock user is active is refused: no caller cookie is injected, so the mock
+// user would stand in for the journey instead of it running signed out.
+//
+// Two refusals keep a data-set journey off the app's real auth database:
+// - `user: none` while auth is configured: a signed-out actor signs in through the auth engine,
+//   which is bound to the real auth database while its requests read the data set;
+// - any data-set journey while a dev mock user is active: the mock user wins over the injected
+//   caller, so the journey would silently act as someone outside the data set.
+//
+// `subject` names the run in the refusals: "journey" for a journey, "call" for the other dev tools
+// that act as someone (resolveToolCaller), which take the same user and data.
+async function resolveJourneyDataSet({
+  data,
+  user,
+  subject = 'journey',
+  configDirectory,
+  buildDirectory,
+  authConfigured,
+  mockUserActive,
+}) {
+  if (type.isNone(data)) {
+    if (user === 'none' && mockUserActive) {
+      return {
+        error: `The ${subject} has user "none", which cannot run while a dev mock user is active (auth.dev.mockUser or LOWDEFY_DEV_USER): with no caller of its own, every request would act as the mock user, not signed out. Remove the mock user to run signed out, or give the ${subject} a user.`,
+      };
+    }
+    if (isUserName(user)) {
+      return {
+        error: `The ${subject}'s user ${JSON.stringify(
+          user
+        )} names a data set user, but the ${subject} has no "data". Add data: <data set name>, or give user as an object.`,
+      };
+    }
+    return { user };
+  }
+  if (mockUserActive) {
+    return {
+      error: `The ${subject} on data set ${JSON.stringify(
+        data
+      )} cannot run while a dev mock user is active (auth.dev.mockUser or LOWDEFY_DEV_USER): every request would act as the mock user, who is not in the data set. Remove the mock user to run on data sets.`,
+    };
+  }
+  if (user === 'none' && authConfigured) {
+    return {
+      error: `The ${subject} on data set ${JSON.stringify(
+        data
+      )} has user "none", which is refused while auth is configured: signing in through the app would write to the app's real auth database. Name a data set user instead; runs that sign in stay off data sets.`,
+    };
+  }
+  let dataSet;
+  try {
+    dataSet = await readDataSet({ configDirectory, buildDirectory, name: data });
+  } catch (error) {
+    return { error: error.message };
+  }
+  if (!isUserName(user)) {
+    return { dataSet, user };
+  }
+  if (!Object.prototype.hasOwnProperty.call(dataSet.users, user)) {
+    return {
+      error: `Data set "${data}" declares no user ${JSON.stringify(user)}. ${describeDeclaredUsers(
+        dataSet
+      )}`,
+    };
+  }
+  return { dataSet, user: dataSet.users[user] };
+}
+
+export default resolveJourneyDataSet;