@commitspark/graphql-api 2.0.0-beta.4 → 2.0.0-beta.5

package/dist/esm/persistence/commit-with-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-with-retry.d.ts","sourceRoot":"","sources":["../../../src/persistence/commit-with-retry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EAGZ,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAK5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,aAAa,EACtB,aAAa,MAAM,OAAO,CAAC,WAAW,CAAC,KACtC,OAAO,CAAC,IAAI,CAqBd,CAAA"}

package/dist/esm/persistence/commit-with-retry.js

@@ -0,0 +1,35 @@
+import { ErrorCode as GitAdapterErrorCode, GitAdapterError, } from '@commitspark/git-adapter';
+import { callGitAdapter, toGraphQLError } from "./git-adapter-call.js";
+const MAX_COMMIT_ATTEMPTS = 3;
+/**
+ * Commits a draft that `createDraft` validates against the current commit of the request, guaranteeing that the
+ * draft is only committed on top of the exact commit it was validated against.
+ *
+ * Git adapters only move a branch if it still points to `parentSha` and otherwise throw `CONFLICT`. As most adapters
+ * can only check this for the branch as a whole, any concurrent commit to the branch between reading and committing
+ * leads to `CONFLICT`, even if it changed unrelated entries. In this case, the current commit of the request is moved
+ * to the new branch head and the draft is created and validated again, including expected entry versions and
+ * references, so that only actual conflicts are reported to the caller.
+ *
+ * Errors thrown by `createDraft` are not retried, as the draft was validated against the latest known state.
+ */
+export const commitWithRetry = async (context, createDraft) => {
+    for (let attempt = 1;; attempt++) {
+        const commitDraft = await createDraft();
+        try {
+            const commit = await context.gitAdapter.createCommit(commitDraft);
+            context.setCurrentHash(commit.commitHash);
+            return;
+        }
+        catch (err) {
+            const isConflict = err instanceof GitAdapterError &&
+                err.code === GitAdapterErrorCode.CONFLICT;
+            if (!isConflict || attempt >= MAX_COMMIT_ATTEMPTS) {
+                throw toGraphQLError(err);
+            }
+        }
+        const headCommitHash = await callGitAdapter(() => context.gitAdapter.getLatestCommitHash(context.branch));
+        context.setCurrentHash(headCommitHash);
+    }
+};
+//# sourceMappingURL=commit-with-retry.js.map

package/dist/esm/persistence/commit-with-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-with-retry.js","sourceRoot":"","sources":["../../../src/persistence/commit-with-retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,SAAS,IAAI,mBAAmB,EAChC,eAAe,GAChB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEtE,MAAM,mBAAmB,GAAG,CAAC,CAAA;AAE7B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,OAAsB,EACtB,WAAuC,EACxB,EAAE;IACjB,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,MAAM,WAAW,GAAG,MAAM,WAAW,EAAE,CAAA;QACvC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,WAAW,CAAC,CAAA;YACjE,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;YACzC,OAAM;QACR,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,UAAU,GACd,GAAG,YAAY,eAAe;gBAC9B,GAAG,CAAC,IAAI,KAAK,mBAAmB,CAAC,QAAQ,CAAA;YAC3C,IAAI,CAAC,UAAU,IAAI,OAAO,IAAI,mBAAmB,EAAE,CAAC;gBAClD,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;YAC3B,CAAC;QACH,CAAC;QAED,MAAM,cAAc,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,CAC/C,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,OAAO,CAAC,MAAM,CAAC,CACvD,CAAA;QACD,OAAO,CAAC,cAAc,CAAC,cAAc,CAAC,CAAA;IACxC,CAAC;AACH,CAAC,CAAA"}

package/dist/esm/persistence/git-adapter-call.d.ts

@@ -0,0 +1,10 @@
+import { GraphQLError } from 'graphql';
+/**
+ * Converts an error thrown by a Git adapter to a GraphQL error, keeping the error code of a `GitAdapterError`.
+ */
+export declare const toGraphQLError: (err: unknown) => GraphQLError;
+/**
+ * Runs a Git adapter operation and converts thrown errors to GraphQL errors.
+ */
+export declare const callGitAdapter: <T>(operation: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=git-adapter-call.d.ts.map

package/dist/esm/persistence/git-adapter-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-adapter-call.d.ts","sourceRoot":"","sources":["../../../src/persistence/git-adapter-call.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAGtC;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,OAAO,KAAG,YAM7C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EACpC,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,KAC1B,OAAO,CAAC,CAAC,CAMX,CAAA"}

package/dist/esm/persistence/git-adapter-call.js

@@ -0,0 +1,24 @@
+import { GitAdapterError } from '@commitspark/git-adapter';
+import { createError, ErrorCode } from "../graphql/errors.js";
+/**
+ * Converts an error thrown by a Git adapter to a GraphQL error, keeping the error code of a `GitAdapterError`.
+ */
+export const toGraphQLError = (err) => {
+    if (err instanceof GitAdapterError) {
+        return createError(err.message, err.code, {});
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return createError(message, ErrorCode.INTERNAL_ERROR, {});
+};
+/**
+ * Runs a Git adapter operation and converts thrown errors to GraphQL errors.
+ */
+export const callGitAdapter = async (operation) => {
+    try {
+        return await operation();
+    }
+    catch (err) {
+        throw toGraphQLError(err);
+    }
+};
+//# sourceMappingURL=git-adapter-call.js.map

package/dist/esm/persistence/git-adapter-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-adapter-call.js","sourceRoot":"","sources":["../../../src/persistence/git-adapter-call.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE1D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAE7D;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAY,EAAgB,EAAE;IAC3D,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;QACnC,OAAO,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAC/C,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAChE,OAAO,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,cAAc,EAAE,EAAE,CAAC,CAAA;AAC3D,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EACjC,SAA2B,EACf,EAAE;IACd,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAA;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;IAC3B,CAAC;AACH,CAAC,CAAA"}

package/dist/esm/persistence/persistence.d.ts

@@ -4,4 +4,15 @@ export declare function getTypeById(context: ApolloContext, id: string): Promise
 export declare function findById(context: ApolloContext, id: string): Promise<Entry>;
 export declare function findByType(context: ApolloContext, type: string): Promise<Entry[]>;
 export declare function findByTypeId(context: ApolloContext, type: string, id: string): Promise<Entry>;
+/**
+ * Returns the version of an entry, which is the content hash of the entry reported by the Git adapter. It changes
+ * whenever the stored entry changes.
+ */
+export declare function getEntryVersion(context: ApolloContext, id: string): Promise<string>;
+/**
+ * Throws `CONFLICT` if an expected version is given and the entry has a different version at the current commit of
+ * the request. This lets callers detect that an entry was changed by someone else since they read it, e.g. while a
+ * user was editing the entry, instead of overwriting these changes.
+ */
+export declare function assertExpectedVersion(context: ApolloContext, id: string, expectedVersion: string | null | undefined): Promise<void>;
 //# sourceMappingURL=persistence.d.ts.map

package/dist/esm/persistence/persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/persistence/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,wBAAsB,WAAW,CAC/B,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,KAAK,CAAC,CAchB;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,KAAK,EAAE,CAAC,CAMlB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,KAAK,CAAC,CAehB"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/persistence/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,wBAAsB,WAAW,CAC/B,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,KAAK,CAAC,CAchB;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,KAAK,EAAE,CAAC,CAMlB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,KAAK,CAAC,CAehB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,MAAM,EACV,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACzC,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/esm/persistence/persistence.js

@@ -1,4 +1,4 @@
-import { createError } from "../graphql/errors.js";
+import { createError, ErrorCode } from "../graphql/errors.js";
 export async function getTypeById(context, id) {
     const requestedEntry = await findById(context, id);
     return requestedEntry.metadata.type;
@@ -7,7 +7,7 @@ export async function findById(context, id) {
     const entriesRecord = await context.repositoryCache.getEntriesRecord(context, context.getCurrentHash());
     const requestedEntry = entriesRecord.byId.get(id);
     if (requestedEntry === undefined) {
-        throw createError(`No entry with ID "${id}" exists.`, "NOT_FOUND" /* ErrorCode.NOT_FOUND */, {
+        throw createError(`No entry with ID "${id}" exists.`, ErrorCode.NOT_FOUND, {
             argumentName: 'id',
             argumentValue: id,
         });
@@ -21,7 +21,7 @@ export async function findByType(context, type) {
 export async function findByTypeId(context, type, id) {
     const entryById = await findById(context, id);
     if (entryById === undefined || entryById.metadata.type !== type) {
-        throw createError(`No entry of type "${type}" with ID "${id}" exists.`, "NOT_FOUND" /* ErrorCode.NOT_FOUND */, {
+        throw createError(`No entry of type "${type}" with ID "${id}" exists.`, ErrorCode.NOT_FOUND, {
             typeName: type,
             argumentName: 'id',
             argumentValue: id,
@@ -29,4 +29,37 @@ export async function findByTypeId(context, type, id) {
     }
     return entryById;
 }
+/**
+ * Returns the version of an entry, which is the content hash of the entry reported by the Git adapter. It changes
+ * whenever the stored entry changes.
+ */
+export async function getEntryVersion(context, id) {
+    const entriesRecord = await context.repositoryCache.getEntriesRecord(context, context.getCurrentHash());
+    const version = entriesRecord.hashById.get(id);
+    if (version === undefined) {
+        throw createError(`No entry with ID "${id}" exists.`, ErrorCode.NOT_FOUND, {
+            argumentName: 'id',
+            argumentValue: id,
+        });
+    }
+    return version;
+}
+/**
+ * Throws `CONFLICT` if an expected version is given and the entry has a different version at the current commit of
+ * the request. This lets callers detect that an entry was changed by someone else since they read it, e.g. while a
+ * user was editing the entry, instead of overwriting these changes.
+ */
+export async function assertExpectedVersion(context, id, expectedVersion) {
+    if (expectedVersion === undefined || expectedVersion === null) {
+        return;
+    }
+    const currentVersion = await getEntryVersion(context, id);
+    if (currentVersion !== expectedVersion) {
+        throw createError(`Entry with ID "${id}" has been changed: expected version "${expectedVersion}" but current version is ` +
+            `"${currentVersion}".`, ErrorCode.CONFLICT, {
+            argumentName: 'expectedVersion',
+            argumentValue: expectedVersion,
+        });
+    }
+}
 //# sourceMappingURL=persistence.js.map

package/dist/esm/persistence/persistence.js.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../../src/persistence/persistence.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAa,MAAM,sBAAsB,CAAA;AAG7D,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAsB,EACtB,EAAU;IAEV,MAAM,cAAc,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IAClD,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAA;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAAsB,EACtB,EAAU;IAEV,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,gBAAgB,CAClE,OAAO,EACP,OAAO,CAAC,cAAc,EAAE,CACzB,CAAA;IACD,MAAM,cAAc,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IACjD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,WAAW,CAAC,qBAAqB,EAAE,WAAW,yCAAuB;YACzE,YAAY,EAAE,IAAI;YAClB,aAAa,EAAE,EAAE;SAClB,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,cAAc,CAAA;AACvB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAsB,EACtB,IAAY;IAEZ,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,gBAAgB,CAClE,OAAO,EACP,OAAO,CAAC,cAAc,EAAE,CACzB,CAAA;IACD,OAAO,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAsB,EACtB,IAAY,EACZ,EAAU;IAEV,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IAC7C,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAChE,MAAM,WAAW,CACf,qBAAqB,IAAI,cAAc,EAAE,WAAW,yCAEpD;YACE,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,IAAI;YAClB,aAAa,EAAE,EAAE;SAClB,CACF,CAAA;IACH,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC"}
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../../src/persistence/persistence.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAG7D,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAsB,EACtB,EAAU;IAEV,MAAM,cAAc,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IAClD,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAA;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAAsB,EACtB,EAAU;IAEV,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,gBAAgB,CAClE,OAAO,EACP,OAAO,CAAC,cAAc,EAAE,CACzB,CAAA;IACD,MAAM,cAAc,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IACjD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,WAAW,CAAC,qBAAqB,EAAE,WAAW,EAAE,SAAS,CAAC,SAAS,EAAE;YACzE,YAAY,EAAE,IAAI;YAClB,aAAa,EAAE,EAAE;SAClB,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,cAAc,CAAA;AACvB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAsB,EACtB,IAAY;IAEZ,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,gBAAgB,CAClE,OAAO,EACP,OAAO,CAAC,cAAc,EAAE,CACzB,CAAA;IACD,OAAO,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAsB,EACtB,IAAY,EACZ,EAAU;IAEV,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IAC7C,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAChE,MAAM,WAAW,CACf,qBAAqB,IAAI,cAAc,EAAE,WAAW,EACpD,SAAS,CAAC,SAAS,EACnB;YACE,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,IAAI;YAClB,aAAa,EAAE,EAAE;SAClB,CACF,CAAA;IACH,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAsB,EACtB,EAAU;IAEV,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,gBAAgB,CAClE,OAAO,EACP,OAAO,CAAC,cAAc,EAAE,CACzB,CAAA;IACD,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC9C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,WAAW,CAAC,qBAAqB,EAAE,WAAW,EAAE,SAAS,CAAC,SAAS,EAAE;YACzE,YAAY,EAAE,IAAI;YAClB,aAAa,EAAE,EAAE;SAClB,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAsB,EACtB,EAAU,EACV,eAA0C;IAE1C,IAAI,eAAe,KAAK,SAAS,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC9D,OAAM;IACR,CAAC;IACD,MAAM,cAAc,GAAG,MAAM,eAAe,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IACzD,IAAI,cAAc,KAAK,eAAe,EAAE,CAAC;QACvC,MAAM,WAAW,CACf,kBAAkB,EAAE,yCAAyC,eAAe,2BAA2B;YACrG,IAAI,cAAc,IAAI,EACxB,SAAS,CAAC,QAAQ,EAClB;YACE,YAAY,EAAE,iBAAiB;YAC/B,aAAa,EAAE,eAAe;SAC/B,CACF,CAAA;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -9,13 +9,16 @@
     "gitops",
     "api"
   ],
-  "version": "2.0.0-beta.4",
+  "version": "2.0.0-beta.5",
   "license": "ISC",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/commitspark/graphql-api.git"
   },
   "private": false,
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "files": [
     "dist/**",
     "!dist/**/*.tsbuildinfo",
@@ -53,13 +56,13 @@
   },
   "dependencies": {
     "@apollo/server": "^5.2.0",
-    "@commitspark/git-adapter": "^2.0.0-beta.2",
+    "@commitspark/git-adapter": "^2.0.0-beta.4",
     "@commitspark/search-adapter": "^1.0.0-beta.1",
-    "@graphql-tools/schema": "^9.0.0",
-    "@graphql-tools/utils": "^9.0.0"
+    "@graphql-tools/schema": "^11.0.8",
+    "@graphql-tools/utils": "^13.2.1"
   },
   "peerDependencies": {
-    "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0"
+    "graphql": "^16.11.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",

package/src/graphql/errors.ts

@@ -2,13 +2,14 @@ import { GraphQLError } from 'graphql'
 import { ErrorCode as GitAdapterErrorCode } from '@commitspark/git-adapter'
 import { ErrorCode as SearchAdapterErrorCode } from '@commitspark/search-adapter'
 
-export const enum ErrorCode {
+export enum ErrorCode {
   BAD_USER_INPUT = 'BAD_USER_INPUT',
   NOT_FOUND = 'NOT_FOUND',
   BAD_REPOSITORY_DATA = 'BAD_REPOSITORY_DATA',
   BAD_SCHEMA = 'BAD_SCHEMA',
   INTERNAL_ERROR = 'INTERNAL_ERROR',
   IN_USE = 'IN_USE',
+  CONFLICT = 'CONFLICT',
 }
 
 export interface ErrorMetadata {

package/src/graphql/input-type-generator.ts

@@ -10,7 +10,6 @@ import {
   isListType,
   isNonNullType,
   isObjectType,
-  isScalarType,
   isUnionType,
 } from 'graphql'
 import { SchemaAnalyzerResult } from './schema-analyzer.ts'
@@ -72,16 +71,13 @@ export function generateObjectInputTypeStrings(
   return objectTypes.map((objectType): string => {
     const name = objectType.name
     const inputTypeName = `${name}Input`
+    const isEntryType = hasDirective(objectType, ENTRY_DIRECTIVE_NAME)
     let inputType = `input ${inputTypeName} {\n`
     let inputTypeFieldStrings = ''
     for (const fieldsKey in objectType.getFields()) {
       const field = objectType.getFields()[fieldsKey]
-      if (
-        (isNonNullType(field.type) &&
-          isScalarType(field.type.ofType) &&
-          field.type.ofType.name === 'ID') ||
-        (isScalarType(field.type) && field.type.name === 'ID')
-      ) {
+      // the ID of an entry is passed as mutation argument instead of as part of the entry data
+      if (isEntryType && field.name === 'id') {
         continue
       }
       const inputTypeString = generateFieldInputTypeString(field.type)
@@ -103,12 +99,12 @@ export function generateObjectInputTypeStrings(
 export function generateUnionInputTypeStrings(
   unionTypes: GraphQLUnionType[],
 ): string[] {
-  const typeStrings = unionTypes.map((unionType): string => {
+  return unionTypes.map((unionType): string => {
     if (buildsOnTypeWithEntryDirective(unionType)) {
       return ''
     }
 
-    // see https://github.com/graphql/graphql-spec/pull/825
+    // `@oneOf` is a directive specified by GraphQL and built into graphql-js since 16.9
     let unionInputType = `input ${unionType.name}Input @oneOf {\n`
     for (const innerType of unionType.getTypes()) {
       unionInputType += `  ${innerType.name}: ${innerType.name}Input\n`
@@ -116,10 +112,4 @@ export function generateUnionInputTypeStrings(
     unionInputType += '}\n'
     return unionInputType
   })
-
-  if (typeStrings.join('').length > 0) {
-    typeStrings.push('directive @oneOf on INPUT_OBJECT\n')
-  }
-
-  return typeStrings
 }

package/src/graphql/queries-mutations-generator.ts

@@ -8,12 +8,16 @@ import { mutationDeleteResolver } from './resolvers/query-mutation-resolvers/mut
 import { queryTypeByIdResolver } from './resolvers/query-mutation-resolvers/query-type-by-id-resolver.ts'
 import { querySearchResolver } from './resolvers/query-mutation-resolvers/query-search-resolver.ts'
 import { referencedByResolver } from './resolvers/field-resolvers/referenced-by-resolver.ts'
+import { versionResolver } from './resolvers/field-resolvers/version-resolver.ts'
 import {
   QueryMutationResolver,
   ReferencedByResolver,
   SearchQueryResolver,
+  VersionResolver,
 } from './resolvers/types.ts'
 
+const commitInputTypeName = '_CommitInput'
+
 export function generateQueriesAndMutations(
   entryDirectiveTypes: GraphQLObjectType[],
 ): GeneratedSchema[] {
@@ -42,8 +46,20 @@ export function generateQueriesAndMutations(
     ) => queryByIdResolver(source, args, { ...context, type: objectType }, info)
 
     const inputTypeName = `${typeName}Input`
+    // mutations are printed with one argument per line, as indented within the generated root type
+    const commitArgument = (operation: string): string =>
+      '    """\n' +
+      `    Details of the commit. If no message is given, the message is '${operation} ${typeName} "<id>"'.\n` +
+      '    """\n' +
+      `    commit: ${commitInputTypeName}\n`
+    const expectedVersionArgument =
+      '    """\n' +
+      '    Version of the entry (field `_version`) that the change is based on. If given and the entry has a different\n' +
+      '    version, the mutation fails with error code CONFLICT instead of overwriting changes made since.\n' +
+      '    """\n' +
+      '    expectedVersion: String\n'
     const createMutationName = `create${typeName}`
-    const createMutationString = `${createMutationName}(id: ID!, data: ${inputTypeName}!, commitMessage: String): ${typeName}`
+    const createMutationString = `${createMutationName}(\n    id: ID!\n    data: ${inputTypeName}!\n${commitArgument('Create')}  ): ${typeName}`
     const createMutationResolver: QueryMutationResolver<EntryData> = (
       source,
       args,
@@ -58,7 +74,7 @@ export function generateQueriesAndMutations(
       )
 
     const updateMutationName = `update${typeName}`
-    const updateMutationString = `${updateMutationName}(id: ID!, data: ${inputTypeName}!, commitMessage: String): ${typeName}`
+    const updateMutationString = `${updateMutationName}(\n    id: ID!\n    data: ${inputTypeName}!\n${expectedVersionArgument}${commitArgument('Update')}  ): ${typeName}`
     const updateMutationResolver: QueryMutationResolver<EntryData> = (
       source,
       args,
@@ -73,7 +89,7 @@ export function generateQueriesAndMutations(
       )
 
     const deleteMutationName = `delete${typeName}`
-    const deleteMutationString = `${deleteMutationName}(id: ID!, commitMessage: String): ID`
+    const deleteMutationString = `${deleteMutationName}(\n    id: ID!\n${expectedVersionArgument}${commitArgument('Delete')}  ): ID`
     const deleteMutationResolver: QueryMutationResolver<string> = (
       source,
       args,
@@ -117,6 +133,24 @@ export function generateQueriesAndMutations(
   })
 }
 
+export function generateCommitInputType(): string {
+  return `"""
+Details of the commit created by a mutation.
+"""
+input ${commitInputTypeName} {
+  """
+  Commit message summarizing the change in a single line. Leading and trailing whitespace is removed, and messages
+  containing line breaks are rejected with error code BAD_USER_INPUT. If omitted or empty, a message is generated.
+  """
+  message: String
+  """
+  Optional details of the change, which may span multiple lines. Leading and trailing whitespace is removed.
+  """
+  body: String
+}
+`
+}
+
 export function generateTypeNameQuery(): GeneratedQuery {
   const entryTypeQueryName = '_typeName'
   const entryTypeQueryString = `${entryTypeQueryName}(id: ID!): String!`
@@ -147,27 +181,34 @@ export function generateSearchQuery(): GeneratedSearchQuery {
   }
 }
 
-export function generateReferencedByFields(
+export function generateEntryFields(
   entryDirectiveTypes: GraphQLObjectType[],
-): GeneratedField[] {
+): GeneratedEntryFields[] {
   const referencedByFieldName = '_referencedBy'
+  const versionFieldName = '_version'
 
   return entryDirectiveTypes.map((objectType) => ({
     typeName: objectType.name,
-    name: referencedByFieldName,
     typeExtensionString: `extend type ${objectType.name} {
   ${referencedByFieldName}: [ID!]!
+  """
+  Version of the entry, which changes whenever the stored entry changes. Pass it as \`expectedVersion\` to update
+  and delete mutations to prevent overwriting changes made since the entry was read.
+  """
+  ${versionFieldName}: String!
 }
 `,
-    resolver: referencedByResolver,
+    resolvers: {
+      [referencedByFieldName]: referencedByResolver,
+      [versionFieldName]: versionResolver,
+    },
   }))
 }
 
-interface GeneratedField {
+interface GeneratedEntryFields {
   typeName: string
-  name: string
   typeExtensionString: string
-  resolver: ReferencedByResolver
+  resolvers: Record<string, ReferencedByResolver | VersionResolver>
 }
 
 export interface GeneratedSearchQuery {

package/src/graphql/resolvers/commit-message.ts

@@ -0,0 +1,34 @@
+import { CommitDraft } from '@commitspark/git-adapter'
+import { createError, ErrorCode } from '../errors.ts'
+import { CommitInput } from './types.ts'
+
+type MutationOperation = 'Create' | 'Update' | 'Delete'
+
+/**
+ * Determines message and body of the commit of a mutation from mutation argument `commit`. The message is trimmed and
+ * must be a single line; an omitted or empty message is replaced by a message generated from the mutation. The body
+ * is trimmed and omitted if empty.
+ */
+export function getCommitMessage(
+  commit: CommitInput | null | undefined,
+  operation: MutationOperation,
+  typeName: string,
+  id: string,
+): Pick<CommitDraft, 'message' | 'body'> {
+  const message = commit?.message?.trim() ?? ''
+  if (/[\r\n]/.test(message)) {
+    throw createError(
+      'Commit message must be a single line; use field "body" for details.',
+      ErrorCode.BAD_USER_INPUT,
+      { argumentName: 'commit.message', argumentValue: commit?.message },
+    )
+  }
+  const body = commit?.body?.trim() ?? ''
+
+  const commitMessage =
+    message !== '' ? message : `${operation} ${typeName} "${id}"`
+  if (body === '') {
+    return { message: commitMessage }
+  }
+  return { message: commitMessage, body: body }
+}

package/src/graphql/resolvers/field-resolvers/version-resolver.ts

@@ -0,0 +1,8 @@
+import { getEntryVersion } from '../../../persistence/persistence.ts'
+import { VersionResolver } from '../types.ts'
+
+export const versionResolver: VersionResolver = async (
+  source,
+  _args,
+  context,
+) => getEntryVersion(context, source.id)

package/src/graphql/resolvers/query-mutation-resolvers/mutation-create-resolver.ts

@@ -8,6 +8,8 @@ import {
 } from '@commitspark/git-adapter'
 import { QueryMutationResolver } from '../types.ts'
 import { createError, ErrorCode } from '../../errors.ts'
+import { getCommitMessage } from '../commit-message.ts'
+import { commitWithRetry } from '../../../persistence/commit-with-retry.ts'
 
 export const mutationCreateResolver: QueryMutationResolver<EntryData> = async (
   source,
@@ -23,6 +25,8 @@ export const mutationCreateResolver: QueryMutationResolver<EntryData> = async (
       {},
     )
   }
+  // narrowed type, as narrowing does not apply within the callback below
+  const entryType = context.type
 
   try {
     validateEntryId(args.id)
@@ -36,40 +40,47 @@ export const mutationCreateResolver: QueryMutationResolver<EntryData> = async (
       },
     )
   }
+  const commitMessage = getCommitMessage(
+    args.commit,
+    'Create',
+    context.type.name,
+    args.id,
+  )
 
-  let existingEntry
-  try {
-    existingEntry = await findById(context, args.id)
-  } catch {}
-  if (existingEntry) {
-    throw createError(
-      `An entry with id "${args.id}" already exists.`,
-      ErrorCode.BAD_USER_INPUT,
-      {
-        argumentName: 'id',
-        argumentValue: args.id,
-      },
-    )
-  }
+  await commitWithRetry(context, async () => {
+    let existingEntry
+    try {
+      existingEntry = await findById(context, args.id)
+    } catch {}
+    if (existingEntry) {
+      throw createError(
+        `An entry with id "${args.id}" already exists.`,
+        ErrorCode.BAD_USER_INPUT,
+        {
+          argumentName: 'id',
+          argumentValue: args.id,
+        },
+      )
+    }
 
-  await validateEntryReferences(context.type, context, args.data ?? null)
+    await validateEntryReferences(entryType, context, args.data ?? null)
 
-  const newEntryDraft: EntryDraft = {
-    id: args.id,
-    metadata: {
-      type: context.type.name,
-    },
-    data: args.data ?? null,
-    deletion: false,
-  }
+    const newEntryDraft: EntryDraft = {
+      id: args.id,
+      metadata: {
+        type: context.type.name,
+      },
+      data: args.data ?? null,
+      deletion: false,
+    }
 
-  const commit = await context.gitAdapter.createCommit({
-    ref: context.branch,
-    parentSha: context.getCurrentHash(),
-    entries: [newEntryDraft],
-    message: args.commitMessage,
+    return {
+      ref: context.branch,
+      parentSha: context.getCurrentHash(),
+      entries: [newEntryDraft],
+      ...commitMessage,
+    }
   })
-  context.setCurrentHash(commit.commitHash)
 
   const newEntry = await findByTypeId(context, context.type.name, args.id)
   return { ...newEntry.data, id: newEntry.id }

package/src/graphql/resolvers/query-mutation-resolvers/mutation-delete-resolver.ts

@@ -1,8 +1,13 @@
-import { findByTypeId } from '../../../persistence/persistence.ts'
+import {
+  assertExpectedVersion,
+  findByTypeId,
+} from '../../../persistence/persistence.ts'
 import { Entry } from '@commitspark/git-adapter'
 import { getReferencingEntryIds } from '../../schema-utils/entry-reference-util.ts'
 import { QueryMutationResolver } from '../types.ts'
 import { createError, ErrorCode } from '../../errors.ts'
+import { getCommitMessage } from '../commit-message.ts'
+import { commitWithRetry } from '../../../persistence/commit-with-retry.ts'
 
 export const mutationDeleteResolver: QueryMutationResolver<string> = async (
   source,
@@ -10,38 +15,47 @@ export const mutationDeleteResolver: QueryMutationResolver<string> = async (
   context,
   info,
 ) => {
-  const entry: Entry = await findByTypeId(context, context.type.name, args.id)
+  const commitMessage = getCommitMessage(
+    args.commit,
+    'Delete',
+    context.type.name,
+    args.id,
+  )
 
-  // references held by the entry itself are deleted together with the entry
-  const otherReferencingIds = (
-    await getReferencingEntryIds(context, info.schema, args.id)
-  ).filter((referencingId) => referencingId !== args.id)
-  if (otherReferencingIds.length > 0) {
-    const otherIds = otherReferencingIds
-      .map((referenceId) => `"${referenceId}"`)
-      .join(', ')
-    throw createError(
-      `Entry with ID "${args.id}" is still referenced by entries [${otherIds}].`,
-      ErrorCode.IN_USE,
-      {
-        argumentName: 'id',
-        argumentValue: args.id,
-      },
-    )
-  }
+  await commitWithRetry(context, async () => {
+    const entry: Entry = await findByTypeId(context, context.type.name, args.id)
+    await assertExpectedVersion(context, args.id, args.expectedVersion)
 
-  const commit = await context.gitAdapter.createCommit({
-    ref: context.branch,
-    parentSha: context.getCurrentHash(),
-    entries: [
-      {
-        ...entry,
-        deletion: true,
-      },
-    ],
-    message: args.commitMessage,
+    // references held by the entry itself are deleted together with the entry
+    const otherReferencingIds = (
+      await getReferencingEntryIds(context, info.schema, args.id)
+    ).filter((referencingId) => referencingId !== args.id)
+    if (otherReferencingIds.length > 0) {
+      const otherIds = otherReferencingIds
+        .map((referenceId) => `"${referenceId}"`)
+        .join(', ')
+      throw createError(
+        `Entry with ID "${args.id}" is still referenced by entries [${otherIds}].`,
+        ErrorCode.IN_USE,
+        {
+          argumentName: 'id',
+          argumentValue: args.id,
+        },
+      )
+    }
+
+    return {
+      ref: context.branch,
+      parentSha: context.getCurrentHash(),
+      entries: [
+        {
+          ...entry,
+          deletion: true,
+        },
+      ],
+      ...commitMessage,
+    }
   })
-  context.setCurrentHash(commit.commitHash)
 
   return args.id
 }