feat: Add isSubjectPopulated precondition (#285)

Author: goloroden

README.md

@@ -78,6 +78,20 @@ const writtenEvents = await client.writeEvents([
 ]);
 ```
 
+#### Using the `isSubjectPopulated` precondition
+
+If you only want to write events in case a subject (such as `/books/42`) already has at least one event, import the `isSubjectPopulated` function and pass it as an array of preconditions in the second argument:
+
+```typescript
+import { isSubjectPopulated } from 'eventsourcingdb';
+
+const writtenEvents = await client.writeEvents([
+  // events
+], [
+  isSubjectPopulated('/books/42')
+]);
+```
+
 #### Using the `isSubjectOnEventId` precondition
 
 If you only want to write events in case the last event of a subject (such as `/books/42`) has a specific ID (e.g., `0`), import the `isSubjectOnEventId` function and pass it as an array of preconditions in the second argument:

src/Precondition.ts

@@ -2,6 +2,10 @@ interface IsSubjectPristinePrecondition {
 	subject: string;
 }
 
+interface IsSubjectPopulatedPrecondition {
+	subject: string;
+}
+
 interface IsSubjectOnEventIdPrecondition {
 	subject: string;
 	eventId: string;
@@ -20,6 +24,10 @@ type Precondition =
 			type: 'isSubjectOnEventId';
 			payload: IsSubjectOnEventIdPrecondition;
 	  }
+	| {
+			type: 'isSubjectPopulated';
+			payload: IsSubjectPopulatedPrecondition;
+	  }
 	| {
 			type: 'isEventQlQueryTrue';
 			payload: IsEventQlQueryTruePrecondition;

src/index.ts

@@ -5,12 +5,20 @@ import type { EventCandidate } from './EventCandidate.js';
 import type { EventType } from './EventType.js';
 import { isEventQlQueryTrue } from './isEventQlQueryTrue.js';
 import { isSubjectOnEventId } from './isSubjectOnEventId.js';
+import { isSubjectPopulated } from './isSubjectPopulated.js';
 import { isSubjectPristine } from './isSubjectPristine.js';
 import type { ObserveEventsOptions } from './ObserveEventsOptions.js';
 import type { Precondition } from './Precondition.js';
 import type { ReadEventsOptions } from './ReadEventsOptions.js';
 
-export { Client, Container, isEventQlQueryTrue, isSubjectOnEventId, isSubjectPristine };
+export {
+	Client,
+	Container,
+	isEventQlQueryTrue,
+	isSubjectOnEventId,
+	isSubjectPopulated,
+	isSubjectPristine,
+};
 export type {
 	Event,
 	EventCandidate,

src/isSubjectPopulated.ts

@@ -0,0 +1,10 @@
+import type { Precondition } from './Precondition.js';
+
+const isSubjectPopulated = (subject: string): Precondition => {
+	return {
+		type: 'isSubjectPopulated',
+		payload: { subject },
+	};
+};
+
+export { isSubjectPopulated };

src/writeEvents.test.ts

@@ -5,6 +5,7 @@ import type { EventCandidate } from './EventCandidate.js';
 import { getImageVersionFromDockerfile } from './getImageVersionFromDockerfile.js';
 import { isEventQlQueryTrue } from './isEventQlQueryTrue.js';
 import { isSubjectOnEventId } from './isSubjectOnEventId.js';
+import { isSubjectPopulated } from './isSubjectPopulated.js';
 import { isSubjectPristine } from './isSubjectPristine.js';
 
 suite('writeEvents', { timeout: 30_000 }, () => {
@@ -107,6 +108,50 @@ suite('writeEvents', { timeout: 30_000 }, () => {
 		);
 	});
 
+	test('supports the isSubjectPopulated precondition.', async (): Promise<void> => {
+		const client = container.getClient();
+
+		const firstEvent: EventCandidate = {
+			source: 'https://www.eventsourcingdb.io',
+			subject: '/test',
+			type: 'io.eventsourcingdb.test',
+			data: {
+				value: 23,
+			},
+		};
+
+		const secondEvent: EventCandidate = {
+			source: 'https://www.eventsourcingdb.io',
+			subject: '/test',
+			type: 'io.eventsourcingdb.test',
+			data: {
+				value: 42,
+			},
+		};
+
+		await assert.rejects(
+			async () => {
+				await client.writeEvents([secondEvent], [isSubjectPopulated('/test')]);
+			},
+			error => {
+				assert.ok(error instanceof Error);
+				assert.equal(
+					error.message,
+					"Failed to write events, got HTTP status code '409', expected '200'.",
+				);
+				return true;
+			},
+		);
+
+		await client.writeEvents([firstEvent]);
+
+		const writtenEvents = await client.writeEvents([secondEvent], [isSubjectPopulated('/test')]);
+
+		assert.equal(writtenEvents.length, 1);
+		assert.equal(writtenEvents[0].id, '1');
+		assert.equal(writtenEvents[0].data.value, 42);
+	});
+
 	test('supports the isSubjectOnEventId precondition.', async (): Promise<void> => {
 		const client = container.getClient();