@lowdefy/server-dev 6.0.0 → 7.0.0

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

@@ -0,0 +1,220 @@
+/*
+  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');
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Data set "alpha": Connections "contacts/contacts" and "crm-contacts" both name collection "contacts" in different databases'
+  );
+});
+
+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 refuses a keyed connection naming one collection under a different databaseName from another connection', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets', databaseName: 'app' }));
+  writeConnection('legacy-tickets', mongo({ collection: 'tickets', databaseName: 'legacy' }));
+  writeDataSet('alpha', 'fixtures:\n  tickets: [{ _id: a }]\n');
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Data set "alpha": Connections "legacy-tickets" and "tickets" both name collection "tickets" in different databases'
+  );
+});
+
+test('readDataSet refuses a keyed connection naming one collection under a different databaseUri secret from another connection', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets' }));
+  writeConnection('reporting', {
+    type: 'MongoDBCollection',
+    properties: { databaseUri: { _secret: 'REPORTING_URI' }, collection: 'tickets' },
+  });
+  writeDataSet('alpha', 'fixtures:\n  tickets: [{ _id: a }]\n');
+  await expect(readDataSet({ configDirectory, buildDirectory, name: 'alpha' })).rejects.toThrow(
+    'Connections "reporting" and "tickets" both name collection "tickets" in different databases'
+  );
+});
+
+test('readDataSet warns on the same collision between two unkeyed connections', async () => {
+  writeConnection('tickets', mongo({ collection: 'tickets' }));
+  writeConnection('a', mongo({ collection: 'events', databaseName: 'one' }));
+  writeConnection('b', mongo({ collection: 'events', databaseName: 'two' }));
+  writeConnection('computed', mongo({ collection: { _state: 'c' }, databaseName: 'three' }));
+  writeDataSet('alpha', 'fixtures:\n  tickets: [{ _id: a }]\n');
+  const dataSet = await readDataSet({ configDirectory, buildDirectory, name: 'alpha' });
+  expect(dataSet.warnings).toEqual([
+    'Connections "a" and "b" both name collection "events" in different databases; under a data set they read one database, so they share one collection.',
+  ]);
+});
+
+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;

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

@@ -0,0 +1,130 @@
+/*
+  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 resolveJourneyDataSet from './resolveJourneyDataSet.js';
+
+let configDirectory;
+let buildDirectory;
+
+beforeEach(() => {
+  configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-resolve-journey-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 });
+  fs.writeFileSync(
+    path.join(buildDirectory, 'connections', 'tickets.json'),
+    JSON.stringify({
+      connectionId: 'tickets',
+      type: 'MongoDBCollection',
+      properties: { databaseUri: { _secret: 'MONGODB_URI' }, collection: 'tickets' },
+    })
+  );
+  fs.writeFileSync(
+    path.join(configDirectory, 'tests', 'data', 'empty-org.yaml'),
+    `fixtures:
+  tickets: [{ _id: t1, organizationId: org_a }]
+users:
+  owner: { id: u_1, roles: [admin], organizationId: org_a }
+  member: { id: u_2, roles: [member], organizationId: org_a }
+`
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+});
+
+function resolve(overrides) {
+  return resolveJourneyDataSet({
+    configDirectory,
+    buildDirectory,
+    authConfigured: true,
+    mockUserActive: false,
+    ...overrides,
+  });
+}
+
+test('resolveJourneyDataSet resolves a named user from the data set', async () => {
+  const { dataSet, user, error } = await resolve({ data: 'empty-org', user: 'member' });
+  expect(error).toBeUndefined();
+  expect(user).toEqual({ id: 'u_2', roles: ['member'], organizationId: 'org_a' });
+  expect(dataSet.name).toEqual('empty-org');
+  expect(dataSet.collections).toEqual({ tickets: 'tickets' });
+});
+
+test('resolveJourneyDataSet keeps an inline user on a data set journey', async () => {
+  const { user, dataSet } = await resolve({ data: 'empty-org', user: { id: 'x', roles: [] } });
+  expect(user).toEqual({ id: 'x', roles: [] });
+  expect(dataSet.users.owner.id).toEqual('u_1');
+});
+
+test('resolveJourneyDataSet refuses a user name the data set does not declare', async () => {
+  const { error } = await resolve({ data: 'empty-org', user: 'outsider' });
+  expect(error).toEqual(
+    'Data set "empty-org" declares no user "outsider". Declared: owner, member.'
+  );
+});
+
+test('resolveJourneyDataSet refuses a user name on a journey with no data', async () => {
+  const { error } = await resolve({ user: 'member' });
+  expect(error).toMatch(
+    'The journey\'s user "member" names a data set user, but the journey has no "data".'
+  );
+});
+
+test('resolveJourneyDataSet passes a journey with no data and no named user through untouched', async () => {
+  expect(await resolve({ user: 'none' })).toEqual({ user: 'none' });
+  expect(await resolve({ user: { roles: ['admin'] } })).toEqual({ user: { roles: ['admin'] } });
+});
+
+test('resolveJourneyDataSet refuses user none on a data set while auth is configured', async () => {
+  const { error } = await resolve({ data: 'empty-org', user: 'none' });
+  expect(error).toMatch('has user "none", which is refused while auth is configured');
+});
+
+test('resolveJourneyDataSet allows user none on a data set when auth is not configured', async () => {
+  const { error, user } = await resolve({ data: 'empty-org', user: 'none', authConfigured: false });
+  expect(error).toBeUndefined();
+  expect(user).toEqual('none');
+});
+
+test.each([['member'], [{ id: 'x', roles: ['admin'] }], [undefined]])(
+  'resolveJourneyDataSet refuses a data set journey with user %j while a dev mock user is active',
+  async (user) => {
+    const { error } = await resolve({ data: 'empty-org', user, mockUserActive: true });
+    expect(error).toMatch('cannot run while a dev mock user is active');
+  }
+);
+
+test('resolveJourneyDataSet returns readDataSet errors as its own', async () => {
+  const { error } = await resolve({ data: 'missing', user: 'member' });
+  expect(error).toEqual('Data set "missing" not found in tests/data. Declared: empty-org.');
+});
+
+test('resolveJourneyDataSet refuses user none while a dev mock user is active', async () => {
+  const { error } = await resolve({ user: 'none', mockUserActive: true });
+  expect(error).toMatch(
+    'The journey has user "none", which cannot run while a dev mock user is active'
+  );
+});
+
+test('resolveJourneyDataSet keeps user none when no dev mock user is active', async () => {
+  expect(await resolve({ user: 'none' })).toEqual({ user: 'none' });
+});

package/lib/docs/dataSets/sweepOrphanDatabases.js

@@ -0,0 +1,33 @@
+/*
+  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';
+
+// Drops every session database on the store that no registered session owns: one left behind by a
+// write that was still in flight when its session dropped the database, or by a dev server that
+// stopped mid-run.
+async function sweepOrphanDatabases({ client }) {
+  const owned = new Set([...dataSessionRegistry.values()].map((session) => session.databaseName));
+  const { databases } = await client.db('admin').admin().listDatabases({ nameOnly: true });
+  await Promise.all(
+    databases
+      .map((database) => database.name)
+      .filter((name) => name.startsWith('ld_') && !owned.has(name))
+      .map((name) => client.db(name).dropDatabase())
+  );
+}
+
+export default sweepOrphanDatabases;