@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/dataSets/openDataSession.mongodb.test.mjs

@@ -0,0 +1,343 @@
+/*
+  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 { jest } from '@jest/globals';
+import { MongoClient, ObjectId } from 'mongodb';
+import { parseDataSet } from '@lowdefy/node-utils';
+
+import dataSessionRegistry from './dataSessionRegistry.js';
+import getDataStore from './getDataStore.js';
+import openDataSession from './openDataSession.js';
+import readDataSession from './readDataSession.js';
+import { journeyActorToken } from '../../server/auth/journeyActor.js';
+
+jest.setTimeout(120000);
+
+let store;
+let client;
+
+beforeAll(async () => {
+  store = await getDataStore();
+  client = new MongoClient(store.uri);
+  await client.connect();
+});
+
+afterAll(async () => {
+  await client.close();
+  await store.stop();
+});
+
+function makeDataSet(overrides) {
+  return {
+    name: 'sample',
+    fixtures: {},
+    generated: {},
+    indexes: {},
+    users: {},
+    collections: {},
+    ...overrides,
+  };
+}
+
+function sessionDb(session) {
+  return client.db(session.databaseName);
+}
+
+function cookieFor(id) {
+  return `lowdefy_journey_data=${journeyActorToken}.${id}`;
+}
+
+async function listDatabaseNames() {
+  const { databases } = await client.db('admin').admin().listDatabases({ nameOnly: true });
+  return databases.map((database) => database.name);
+}
+
+test('openDataSession creates indexes before documents, so a fixture duplicating a unique key fails naming both', async () => {
+  const dataSet = makeDataSet({
+    collections: { tickets: 'tickets' },
+    indexes: { tickets: [{ key: { number: 1 }, name: 'number_1', unique: true }] },
+    fixtures: {
+      tickets: [
+        { _id: 'f0', number: 7 },
+        { _id: 'f1', number: 7 },
+      ],
+    },
+  });
+  await expect(openDataSession({ dataSet })).rejects.toThrow(
+    'Data set "sample" fixture tickets[1] breaks unique index "number_1": duplicate key {"number":7} held by document _id "f0".'
+  );
+  expect([...dataSessionRegistry.values()].filter((s) => s.name === 'sample')).toEqual([]);
+});
+
+test('openDataSession drops expireAfterSeconds, creates a text index and lets a later index replace one with the same key', async () => {
+  const dataSet = makeDataSet({
+    collections: { events: 'events', 'events-archive': 'events' },
+    fixtures: {
+      events: [{ _id: 'e1', title: 'hello', created: { '~d': '2000-01-01T00:00:00.000Z' } }],
+    },
+    indexes: {
+      events: [
+        { key: { created: 1 }, name: 'created_ttl', expireAfterSeconds: 60 },
+        {
+          key: { _fts: 'text', _ftsx: 1 },
+          name: 'title_text',
+          weights: { title: 1 },
+          default_language: 'english',
+          language_override: 'language',
+          textIndexVersion: 3,
+        },
+        { key: { organizationId: 1 }, name: 'org_1' },
+      ],
+      'events-archive': [{ key: { organizationId: 1 }, name: 'org_unique', unique: true }],
+    },
+  });
+  const { session, close } = await openDataSession({ dataSet });
+  try {
+    const indexes = await sessionDb(session).collection('events').indexes();
+    const byName = Object.fromEntries(indexes.map((index) => [index.name, index]));
+    expect(byName.created_ttl.expireAfterSeconds).toBeUndefined();
+    expect(byName.title_text.weights).toEqual({ title: 1 });
+    expect(byName.org_1).toBeUndefined();
+    expect(byName.org_unique.unique).toBe(true);
+    const found = await sessionDb(session)
+      .collection('events')
+      .find({ $text: { $search: 'hello' } })
+      .toArray();
+    expect(found.map((document) => document._id)).toEqual(['e1']);
+  } finally {
+    await close();
+  }
+});
+
+test('openDataSession lets a later fixture replace one with the same _id and revives dates and ObjectIds', async () => {
+  const oid = new ObjectId();
+  const dataSet = makeDataSet({
+    collections: { tickets: 'tickets', 'tickets-archive': 'tickets' },
+    fixtures: {
+      tickets: [
+        { _id: 't1', title: 'first' },
+        { _id: 't1', title: 'from fixture' },
+      ],
+      'tickets-archive': [
+        {
+          title: 'no id',
+          due: { '~d': '2026-01-02T00:00:00.000Z' },
+          ref: { _oid: oid.toHexString() },
+        },
+      ],
+    },
+  });
+  const { session, close } = await openDataSession({ dataSet });
+  try {
+    const tickets = sessionDb(session).collection('tickets');
+    expect(await tickets.findOne({ _id: 't1' })).toEqual({ _id: 't1', title: 'from fixture' });
+    const noId = await tickets.findOne({ title: 'no id' });
+    expect(noId.due).toEqual(new Date('2026-01-02T00:00:00.000Z'));
+    expect(noId.ref).toEqual(oid);
+    expect(await tickets.countDocuments()).toBe(2);
+  } finally {
+    await close();
+  }
+});
+
+test('openDataSession loads fixtures and generated documents together, with generated dates as Dates', async () => {
+  const configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-generate-'));
+  try {
+    fs.mkdirSync(path.join(configDirectory, 'tests', 'data'), { recursive: true });
+    fs.writeFileSync(
+      path.join(configDirectory, 'tests', 'data', 'invoices.yaml'),
+      [
+        'fixtures:',
+        '  customers_db:',
+        '    - { _id: c-fixture, name: Fixture customer }',
+        'generate:',
+        '  seed: 7',
+        '  customers_db:',
+        '    count: 4',
+        '    fields:',
+        '      name: { company: true }',
+        '  invoices_db:',
+        '    count: 30',
+        '    fields:',
+        '      _id: { sequence: { prefix: inv-, start: 1 } }',
+        '      status: { oneOf: [draft, sent, paid], weights: [1, 2, 5] }',
+        '      issued: { date: { from: 2026-01-01, to: 2026-09-30 } }',
+        '      customerId: { ref: customers_db }',
+        '',
+      ].join('\n')
+    );
+    const parsed = await parseDataSet({ configDirectory, name: 'invoices' });
+    const dataSet = makeDataSet({
+      ...parsed,
+      name: 'sample',
+      collections: { customers_db: 'customers', invoices_db: 'invoices' },
+    });
+    const { session, close } = await openDataSession({ dataSet });
+    try {
+      const customers = await sessionDb(session)
+        .collection('customers')
+        .find({})
+        .sort({ _id: 1 })
+        .toArray();
+      expect(customers.map(({ _id }) => _id)).toEqual([
+        'c-fixture',
+        'customers_db-1',
+        'customers_db-2',
+        'customers_db-3',
+        'customers_db-4',
+      ]);
+      const invoices = await sessionDb(session).collection('invoices').find({}).toArray();
+      expect(invoices).toHaveLength(30);
+      expect(invoices[0]._id).toEqual('inv-1');
+      expect(invoices[0].issued).toBeInstanceOf(Date);
+      const customerIds = customers.map(({ _id }) => _id);
+      invoices.forEach((invoice) => expect(customerIds).toContain(invoice.customerId));
+      expect(
+        await sessionDb(session).collection('invoices').countDocuments({ status: 'paid' })
+      ).toEqual(parsed.generated.invoices_db.filter(({ status }) => status === 'paid').length);
+    } finally {
+      await close();
+    }
+  } finally {
+    fs.rmSync(configDirectory, { recursive: true, force: true });
+  }
+});
+
+test('openDataSession fails naming the generated document that breaks a unique index', async () => {
+  const dataSet = makeDataSet({
+    collections: { tickets: 'tickets' },
+    indexes: { tickets: [{ key: { status: 1 }, name: 'status_1', unique: true }] },
+    generated: {
+      tickets: [
+        { _id: 'g1', status: 'open' },
+        { _id: 'g2', status: 'closed' },
+        { _id: 'g3', status: 'open' },
+      ],
+    },
+  });
+  await expect(openDataSession({ dataSet })).rejects.toThrow(
+    'Data set "sample" generated tickets[2] (_id "g3") breaks unique index "status_1": duplicate key { status: "open" }.'
+  );
+});
+
+test('a session database runs a transaction and opens a change stream', async () => {
+  const dataSet = makeDataSet({
+    collections: { tickets: 'tickets' },
+    fixtures: { tickets: [{ _id: 't1' }] },
+  });
+  const { session, close } = await openDataSession({ dataSet });
+  const sessionClient = new MongoClient(session.databaseUri);
+  await sessionClient.connect();
+  try {
+    const tickets = sessionClient.db(session.databaseName).collection('tickets');
+    const stream = tickets.watch();
+    const next = stream.next();
+    const mongoSession = sessionClient.startSession();
+    await mongoSession.withTransaction(async () => {
+      await tickets.insertOne({ _id: 't2' }, { session: mongoSession });
+    });
+    await mongoSession.endSession();
+    const change = await next;
+    expect(change.documentKey).toEqual({ _id: 't2' });
+    await stream.close();
+    expect(await tickets.countDocuments()).toBe(2);
+  } finally {
+    await sessionClient.close();
+    await close();
+  }
+});
+
+test('two sessions on one data set are isolated, and close() drops the database', async () => {
+  const dataSet = makeDataSet({
+    collections: { tickets: 'tickets' },
+    fixtures: { tickets: [{ _id: 't1' }] },
+  });
+  const first = await openDataSession({ dataSet });
+  const second = await openDataSession({ dataSet });
+  expect(first.session.databaseName).not.toEqual(second.session.databaseName);
+  await sessionDb(first.session).collection('tickets').insertOne({ _id: 'written' });
+  expect(await sessionDb(second.session).collection('tickets').countDocuments()).toBe(1);
+  await first.close();
+  await second.close();
+  const names = await listDatabaseNames();
+  expect(names).not.toContain(first.session.databaseName);
+  expect(names).not.toContain(second.session.databaseName);
+  expect(first.session.state).toEqual('closed');
+});
+
+test('close() waits for background work added to the session', async () => {
+  const { session, close } = await openDataSession({ dataSet: makeDataSet({}) });
+  let release;
+  const work = new Promise((resolve) => {
+    release = resolve;
+  });
+  session.work.add(work);
+  work.then(() => session.work.delete(work));
+  let closed = false;
+  const closing = close().then(() => {
+    closed = true;
+  });
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  expect(closed).toBe(false);
+  expect(session.state).toEqual('closing');
+  release();
+  await closing;
+  expect(closed).toBe(true);
+});
+
+test('close() drops after 30 s with a warning when background work never settles', async () => {
+  const { session, close } = await openDataSession({ dataSet: makeDataSet({}) });
+  await sessionDb(session).collection('kept').insertOne({ _id: 1 });
+  const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  session.work.add(new Promise(() => {}));
+  jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'queueMicrotask', 'performance'] });
+  let warnings;
+  try {
+    const closing = close();
+    jest.advanceTimersByTime(30000);
+    jest.useRealTimers();
+    await closing;
+    warnings = warn.mock.calls.map(([message]) => message);
+  } finally {
+    jest.useRealTimers();
+    warn.mockRestore();
+  }
+  expect(warnings).toEqual([expect.stringContaining('Data set "sample"')]);
+  expect(session.state).toEqual('closed');
+  expect(await listDatabaseNames()).not.toContain(session.databaseName);
+});
+
+test('openDataSession sweeps an ld_ database no open session owns', async () => {
+  await client.db('ld_orphan00000').collection('left').insertOne({ _id: 1 });
+  await client.db('not_a_session').collection('kept').insertOne({ _id: 1 });
+  const { close } = await openDataSession({ dataSet: makeDataSet({}) });
+  const names = await listDatabaseNames();
+  expect(names).not.toContain('ld_orphan00000');
+  expect(names).toContain('not_a_session');
+  await close();
+  await client.db('not_a_session').dropDatabase();
+});
+
+test('readDataSession returns the open session, and { ended } once it closes', async () => {
+  const { id, cookie, session, close } = await openDataSession({ dataSet: makeDataSet({}) });
+  expect(cookie).toEqual(id);
+  expect(readDataSession(cookieFor(id))).toBe(session);
+  await close();
+  expect(readDataSession(cookieFor(id))).toEqual({ ended: id });
+});

package/lib/docs/dataSets/pickDataStorePort.js

@@ -0,0 +1,58 @@
+/*
+  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 crypto from 'node:crypto';
+import net from 'node:net';
+
+// The IANA dynamic range. The store binds above the ports apps usually take (3000 and up), so an
+// app the developer starts while it runs never finds its port held by mongod.
+const MIN_PORT = 49152;
+const MAX_PORT = 65535;
+const MAX_TRIES = 20;
+
+function isPortFree(port) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.once('error', (error) => {
+      // Windows refuses a port inside a range it reserves (Hyper-V, WinNAT) with EACCES, and those
+      // ranges sit inside the dynamic range, so such a port is taken like one in use.
+      if (error.code === 'EADDRINUSE' || error.code === 'EACCES') {
+        resolve(false);
+        return;
+      }
+      reject(error);
+    });
+    server.listen(port, '127.0.0.1', () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+async function pickDataStorePort() {
+  for (let tries = 0; tries < MAX_TRIES; tries += 1) {
+    const port = crypto.randomInt(MIN_PORT, MAX_PORT + 1);
+    if (await isPortFree(port)) {
+      return port;
+    }
+  }
+  throw new Error(
+    `No free port between ${MIN_PORT} and ${MAX_PORT} for the journey data store after ${MAX_TRIES} tries.`
+  );
+}
+
+export { MIN_PORT };
+export default pickDataStorePort;

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

@@ -0,0 +1,63 @@
+/*
+  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 { EventEmitter } from 'node:events';
+import { jest } from '@jest/globals';
+
+const listenErrors = [];
+
+function createServer() {
+  const server = new EventEmitter();
+  server.unref = () => {};
+  server.close = (callback) => callback();
+  server.listen = (port, host, callback) => {
+    const code = listenErrors.shift();
+    if (code === undefined) {
+      callback();
+      return;
+    }
+    server.emit('error', Object.assign(new Error(`listen ${code}`), { code }));
+  };
+  return server;
+}
+
+jest.unstable_mockModule('node:net', () => ({ default: { createServer } }));
+
+const { default: pickDataStorePort, MIN_PORT } = await import('./pickDataStorePort.js');
+
+beforeEach(() => {
+  listenErrors.length = 0;
+});
+
+test('pickDataStorePort tries another port when one is in use or reserved by Windows', async () => {
+  listenErrors.push('EADDRINUSE', 'EACCES');
+  const port = await pickDataStorePort();
+  expect(port).toBeGreaterThanOrEqual(MIN_PORT);
+  expect(port).toBeLessThanOrEqual(65535);
+  expect(listenErrors).toEqual([]);
+});
+
+test('pickDataStorePort rejects on a listen error that is not about the port', async () => {
+  listenErrors.push('EPERM');
+  await expect(pickDataStorePort()).rejects.toThrow('listen EPERM');
+});
+
+test('pickDataStorePort gives up after twenty ports that cannot be taken', async () => {
+  listenErrors.push(...Array(20).fill('EACCES'));
+  await expect(pickDataStorePort()).rejects.toThrow(
+    'No free port between 49152 and 65535 for the journey data store after 20 tries.'
+  );
+});

package/lib/docs/dataSets/readConnectionArtifacts.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 fs from 'node:fs';
+import path from 'node:path';
+
+// Every built connection artifact, keyed by connection id. The build always writes the
+// connections directory when the app declares connections; an app with none has no directory.
+// Module connections are written under their module's folder (connections/<module>/<id>.json),
+// so the directory is read recursively and each artifact keyed by its own connectionId.
+async function readConnectionArtifacts({ buildDirectory }) {
+  const directory = path.join(buildDirectory, 'connections');
+  let fileNames;
+  try {
+    fileNames = await fs.promises.readdir(directory, { recursive: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw error;
+  }
+  const artifacts = {};
+  await Promise.all(
+    fileNames
+      .filter((fileName) => fileName.endsWith('.json'))
+      .map(async (fileName) => {
+        const content = await fs.promises.readFile(path.join(directory, fileName), 'utf8');
+        const artifact = JSON.parse(content);
+        artifacts[artifact.connectionId] = artifact;
+      })
+  );
+  return artifacts;
+}
+
+export default readConnectionArtifacts;

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,68 @@
+/*
+  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 { parseDataSet } from '@lowdefy/node-utils';
+
+import checkSharedCollectionIds from './checkSharedCollectionIds.js';
+import findCollectionCollisions from './findCollectionCollisions.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),
+    ]),
+  ];
+}
+
+// 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 connections that would merge
+// into one collection under the one-database redirect are refused (when the data set names one of
+// them) or reported, and a generated _id that another connection on the same collection also holds
+// is refused. Runs before any browser opens.
+async function readDataSet({ configDirectory, buildDirectory, name }) {
+  const dataSet = await parseDataSet({ configDirectory, name });
+  const warnings = [...dataSet.warnings];
+
+  const artifacts = await readConnectionArtifacts({ buildDirectory });
+  const keyedIds = getKeyedConnectionIds({ dataSet });
+  const collections = {};
+  keyedIds.forEach((connectionId) => {
+    collections[connectionId] = resolveDataSetCollection({
+      dataSetName: name,
+      connectionId,
+      artifact: artifacts[connectionId],
+    }).collection;
+  });
+
+  findCollectionCollisions({ artifacts }).forEach(({ collection, connectionIds }) => {
+    const [a, b] = connectionIds;
+    const message = `Connections "${a}" and "${b}" both name collection "${collection}" in different databases; under a data set they read one database, so they share one collection.`;
+    if (keyedIds.includes(a) || keyedIds.includes(b)) {
+      throw new Error(`Data set "${name}": ${message}`);
+    }
+    warnings.push(message);
+  });
+
+  checkSharedCollectionIds({ dataSetName: name, dataSet: { ...dataSet, collections } });
+
+  return { ...dataSet, collections, warnings };
+}
+
+export default readDataSet;