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

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

@@ -0,0 +1,18 @@
+import { Entry } from '@commitspark/git-adapter';
+import { ApolloContext } from '../client.ts';
+export declare function getTypeById(context: ApolloContext, id: string): Promise<string>;
+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

@@ -0,0 +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;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":"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"}

package/package.json

@@ -9,13 +9,16 @@
     "gitops",
     "api"
   ],
-  "version": "2.0.0-beta.3",
+  "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",
@@ -27,46 +30,52 @@
   ],
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
-  "types": "./dist/types/index.d.ts",
+  "types": "./dist/cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
-      "require": "./dist/cjs/index.js",
-      "import": "./dist/esm/index.js"
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
   "scripts": {
-    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build": "npm run build:cjs && npm run build:esm",
     "build:cjs": "tsc --project tsconfig.build.cjs.json",
     "build:esm": "tsc --project tsconfig.build.esm.json && echo '{\"type\":\"module\"}' > dist/esm/package.json",
-    "build:types": "tsc --project tsconfig.build.types.json",
-    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
     "lint": "eslint \"{src,tests}/**/*.ts\"",
     "test": "jest",
+    "check:package": "attw --pack . && node -e \"require(process.env.npm_package_name)\" && node --input-type=module -e \"await import(process.env.npm_package_name)\"",
     "knip": "knip",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@apollo/server": "^5.2.0",
-    "@commitspark/git-adapter": "^2.0.0-beta.1",
+    "@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": {
-    "@types/jest": "^29.5.2",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/jest": "^30.0.0",
     "@types/node": "^22.14.0",
     "eslint": "^9.24.0",
     "eslint-plugin-import": "^2.32.0",
-    "globals": "^16.0.0",
-    "jest": "^29.5.0",
-    "jest-mock-extended": "^3.0.4",
+    "globals": "^16.5.0",
+    "jest": "^30.2.0",
+    "jest-mock-extended": "^4.0.1",
     "knip": "^5.46.5",
-    "prettier": "^2.4.1",
-    "ts-jest": "^29.1.0",
+    "prettier": "^3.1.1",
+    "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.29.0"

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'
@@ -51,9 +50,7 @@ export function generateIdInputTypeStrings(
   schemaAnalyzerResult: SchemaAnalyzerResult,
 ): string[] {
   let typesWithIdField: (
-    | GraphQLObjectType
-    | GraphQLInterfaceType
-    | GraphQLUnionType
+    GraphQLObjectType | GraphQLInterfaceType | GraphQLUnionType
   )[] = []
   typesWithIdField = typesWithIdField.concat(
     schemaAnalyzerResult.entryDirectiveTypes,
@@ -74,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)
@@ -105,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`
@@ -118,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

@@ -7,11 +7,17 @@ import { mutationUpdateResolver } from './resolvers/query-mutation-resolvers/mut
 import { mutationDeleteResolver } from './resolvers/query-mutation-resolvers/mutation-delete-resolver.ts'
 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[] {
@@ -40,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,
@@ -56,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,
@@ -71,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,
@@ -115,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!`
@@ -145,6 +181,36 @@ export function generateSearchQuery(): GeneratedSearchQuery {
   }
 }
 
+export function generateEntryFields(
+  entryDirectiveTypes: GraphQLObjectType[],
+): GeneratedEntryFields[] {
+  const referencedByFieldName = '_referencedBy'
+  const versionFieldName = '_version'
+
+  return entryDirectiveTypes.map((objectType) => ({
+    typeName: objectType.name,
+    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!
+}
+`,
+    resolvers: {
+      [referencedByFieldName]: referencedByResolver,
+      [versionFieldName]: versionResolver,
+    },
+  }))
+}
+
+interface GeneratedEntryFields {
+  typeName: string
+  typeExtensionString: string
+  resolvers: Record<string, ReferencedByResolver | VersionResolver>
+}
+
 export interface GeneratedSearchQuery {
   name: string
   schemaString: string

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/referenced-by-resolver.ts

@@ -0,0 +1,9 @@
+import { getReferencingEntryIds } from '../../schema-utils/entry-reference-util.ts'
+import { ReferencedByResolver } from '../types.ts'
+
+export const referencedByResolver: ReferencedByResolver = async (
+  source,
+  _args,
+  context,
+  info,
+) => getReferencingEntryIds(context, info.schema, source.id)

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

@@ -1,13 +1,15 @@
 import { findById, findByTypeId } from '../../../persistence/persistence.ts'
 import { isObjectType } from 'graphql'
-import { getReferencedEntryIds } from '../../schema-utils/entry-reference-util.ts'
+import { validateEntryReferences } from '../../schema-utils/entry-reference-util.ts'
 import {
-  ENTRY_ID_INVALID_CHARACTERS,
   EntryData,
   EntryDraft,
+  validateEntryId,
 } 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,
@@ -15,6 +17,7 @@ export const mutationCreateResolver: QueryMutationResolver<EntryData> = async (
   context,
   info,
 ) => {
+  void info
   if (!isObjectType(context.type)) {
     throw createError(
       `Entry of type "${context.type.name}" cannot be created as is not an ObjectType.`,
@@ -22,28 +25,14 @@ export const mutationCreateResolver: QueryMutationResolver<EntryData> = async (
       {},
     )
   }
+  // narrowed type, as narrowing does not apply within the callback below
+  const entryType = context.type
 
-  const idValidationResult = args.id.match(ENTRY_ID_INVALID_CHARACTERS)
-  if (idValidationResult) {
-    throw createError(
-      `Field "id" contains invalid characters "${idValidationResult.join(
-        ', ',
-      )}".`,
-      ErrorCode.BAD_USER_INPUT,
-      {
-        argumentName: 'id',
-        argumentValue: args.id,
-      },
-    )
-  }
-
-  let existingEntry
   try {
-    existingEntry = await findById(context, args.id)
-  } catch {}
-  if (existingEntry) {
+    validateEntryId(args.id)
+  } catch (err) {
     throw createError(
-      `An entry with id "${args.id}" already exists.`,
+      err instanceof Error ? err.message : String(err),
       ErrorCode.BAD_USER_INPUT,
       {
         argumentName: 'id',
@@ -51,50 +40,47 @@ export const mutationCreateResolver: QueryMutationResolver<EntryData> = async (
       },
     )
   }
-
-  const referencedEntryIds = await getReferencedEntryIds(
-    context.type,
-    context,
-    null,
-    info.returnType,
-    args.data ?? null,
+  const commitMessage = getCommitMessage(
+    args.commit,
+    'Create',
+    context.type.name,
+    args.id,
   )
 
-  const referencedEntryUpdates: EntryDraft[] = []
-  for (const referencedEntryId of referencedEntryIds) {
-    const referencedEntry = await findById(context, referencedEntryId)
-    const newReferencedEntryIds: string[] = [
-      ...(referencedEntry.metadata.referencedBy ?? []),
-      args.id,
-    ].sort()
-    const newReferencedEntryDraft: EntryDraft = {
-      ...referencedEntry,
+  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(entryType, context, args.data ?? null)
+
+    const newEntryDraft: EntryDraft = {
+      id: args.id,
       metadata: {
-        ...referencedEntry.metadata,
-        referencedBy: newReferencedEntryIds,
+        type: context.type.name,
       },
+      data: args.data ?? null,
       deletion: false,
     }
-    referencedEntryUpdates.push(newReferencedEntryDraft)
-  }
-
-  const newEntryDraft: EntryDraft = {
-    id: args.id,
-    metadata: {
-      type: context.type.name,
-      referencedBy: [],
-    },
-    data: args.data ?? null,
-    deletion: false,
-  }
 
-  const commit = await context.gitAdapter.createCommit({
-    ref: context.branch,
-    parentSha: context.getCurrentHash(),
-    entries: [newEntryDraft, ...referencedEntryUpdates],
-    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 }