@contember/migrations-client 1.4.0-alpha.5

package/src/MigrationFile.ts

@@ -0,0 +1,52 @@
+import { Migration } from '@contember/schema-migrations'
+import { JSONObject } from './utils/json'
+
+export interface MigrationFile {
+	path: string
+	version: string
+	name: string
+
+	getContent: () => Promise<MigrationContent>
+}
+
+export const isSchemaMigration = (content: MigrationContent): content is SchemaMigration => typeof content !== 'function' && 'modifications' in content
+
+export type ResolvedMigrationContent =
+	| SchemaMigration
+	| ContentMigration
+
+export type MigrationContent =
+	| ResolvedMigrationContent
+	| ContentMigrationFactory
+
+export type SchemaMigration =
+	& {
+		type: 'schema'
+	}
+	& Migration
+
+export type ContentMigration = {
+	type: 'content'
+	version: string
+	name: string
+	queries: ContentMigrationQuery[]
+}
+
+export type ContentMigrationFactoryArgs = {
+	apiBaseUrl: string
+	projectName: string
+	apiToken: string
+}
+
+export type ContentMigrationFactory = {
+	type: 'factory'
+	factory: (args: ContentMigrationFactoryArgs) => Promise<ContentMigration>
+}
+
+export type ContentMigrationQuery = {
+	query: string
+	variables?: JSONObject
+	stage?: string
+	checkMutationResult?: boolean
+}
+

package/src/MigrationFileLoader.ts

@@ -0,0 +1,5 @@
+import { MigrationContent, MigrationFile } from './MigrationFile'
+
+export interface MigrationFileLoader {
+	load(file: MigrationFile): Promise<MigrationContent>
+}

package/src/MigrationFilesManager.ts

@@ -0,0 +1,102 @@
+import { MigrationVersionHelper } from '@contember/engine-common'
+import * as fs from 'node:fs/promises'
+import { MigrationFileLoader } from './MigrationFileLoader'
+import { MigrationContent, MigrationFile } from './MigrationFile'
+import { join } from 'node:path'
+import { Dirent } from 'node:fs'
+
+export class MigrationFilesManager {
+	private migrations: null | Promise<MigrationFile[]> = null
+
+	constructor(
+		public readonly directory: string,
+		private readonly loaders: Record<string, MigrationFileLoader>,
+	) {}
+
+	public async createFile(content: string, name: string, extension = 'json'): Promise<string> {
+		this.migrations = null
+		const path = this.formatPath(name, extension)
+		await fs.writeFile(path, content, { encoding: 'utf8' })
+		return await fs.realpath(path)
+	}
+
+	public async removeFile(name: string) {
+		this.migrations = null
+		const path = this.formatPath(name)
+		await fs.unlink(path)
+	}
+
+	public async moveFile(oldName: string, newName: string) {
+		this.migrations = null
+		await fs.rename(this.formatPath(oldName), this.formatPath(newName))
+	}
+
+	public async createDirIfNotExist(): Promise<void> {
+		try {
+			await fs.mkdir(this.directory)
+		} catch (e) {
+			if (!(e instanceof Error) || !('code' in e) || (e as any).code !== 'EEXIST') {
+				throw e
+			}
+		}
+	}
+
+	public async readFiles(): Promise<MigrationFile[]> {
+		return this.migrations ??= this.forceReadFiles()
+	}
+
+	public async forceReadFiles(): Promise<MigrationFile[]> {
+		const files = (await this.listFiles()).map(it => ({
+			filename: it,
+			version: MigrationVersionHelper.extractVersion(it),
+		}))
+
+		return files.map(({ version, filename }): MigrationFile => {
+			const ext = filename.substring(filename.lastIndexOf('.') + 1)
+			const path = join(this.directory, filename)
+			let content: Promise<MigrationContent> | null = null
+			const file: MigrationFile = {
+				path: path,
+				version: version,
+				name: MigrationVersionHelper.extractName(path.substring(path.lastIndexOf('/') + 1)),
+				getContent: () => {
+					content ??= this.loaders[ext].load(file)
+					return content
+				},
+			}
+			return file
+		})
+	}
+
+	private async tryReadDir(): Promise<Dirent[]> {
+		try {
+			return await fs.readdir(this.directory, { withFileTypes: true })
+		} catch (e) {
+			if (e instanceof Error && 'code' in e && (e as any).code === 'ENOENT') {
+				return []
+			}
+			throw e
+		}
+	}
+
+	private async listFiles(): Promise<string[]> {
+		const files = await this.tryReadDir()
+
+		const extensions = Object.keys(this.loaders).join('|')
+		const regex = new RegExp('^\\d{4}-\\d{2}-\\d{2}-\\d{6}-[\\w-]+\\.(' + extensions  + ')$')
+		const filteredFiles = await Promise.all(
+			files
+				.filter(it => it.isFile())
+				.map(it => it.name)
+				.filter(it => it.match(regex)),
+		)
+
+		return filteredFiles.sort()
+	}
+
+	private formatPath(version: string, extension = 'json'): string {
+		const filename = `${version}.${extension}`
+		const path = `${this.directory}/${filename}`
+		return path
+	}
+}

package/src/MigrationParser.ts

@@ -0,0 +1,32 @@
+import { Migration, VERSION_INITIAL } from '@contember/schema-migrations'
+import { ContentMigrationQuery, MigrationFile, ResolvedMigrationContent } from './MigrationFile'
+import { JSONValue } from './utils/json'
+
+export class MigrationParser {
+	public parse(migrationFile: MigrationFile, content: JSONValue): ResolvedMigrationContent {
+		if (typeof content !== 'object' || content === null) {
+			throw new Error('Invalid migration')
+		}
+
+		if ('modifications' in content) {
+			const validated = content as Migration // todo validate
+
+			return {
+				type: 'schema',
+				version: migrationFile.version,
+				name: migrationFile.name,
+				formatVersion: validated.formatVersion || VERSION_INITIAL,
+				modifications: validated.modifications,
+				...(validated.skippedErrors ? { skippedErrors: validated.skippedErrors } : {}),
+			}
+		} else if ('queries' in content || 'query' in content) {
+			return {
+				type: 'content',
+				version: migrationFile.version,
+				name: migrationFile.name,
+				queries: ('queries' in content ? content.queries : [content]) as ContentMigrationQuery[],
+			}
+		}
+		throw new Error('Invalid migration content')
+	}
+}

package/src/MigrationsResolver.ts

@@ -0,0 +1,44 @@
+import { MigrationFilesManager } from './MigrationFilesManager'
+import { Migration } from '@contember/schema-migrations'
+import { isSchemaMigration, MigrationFile } from './MigrationFile'
+import { MigrationVersionHelper } from '@contember/engine-common'
+
+export class MigrationsResolver {
+
+	constructor(private readonly migrationFilesManager: MigrationFilesManager) {}
+
+	public get directory(): string {
+		return this.migrationFilesManager.directory
+	}
+
+	public async getMigrationFiles(): Promise<MigrationFile[]> {
+		return await this.migrationFilesManager.readFiles()
+	}
+
+	public async getSchemaMigrations(): Promise<Migration[]> {
+		const migrationFiles = await this.getMigrationFiles()
+
+		const migrations = await Promise.all(migrationFiles.map(this.convertMigrationFileToSchemaMigration))
+
+		return migrations.filter((it): it is Migration => it !== null)
+	}
+
+	public async findLatestSchemaMigration(): Promise<Migration | null> {
+		const migrations = await this.getSchemaMigrations()
+		return migrations.length > 0 ? migrations[migrations.length - 1] : null
+	}
+
+	public async findSchemaMigrationByVersion(version: string): Promise<Migration | null> {
+		const migrations = await this.getSchemaMigrations()
+		return migrations
+			.find(it =>
+				MigrationVersionHelper.extractVersion(it.version) === MigrationVersionHelper.extractVersion(version),
+			)
+			?? null
+	}
+
+	private async convertMigrationFileToSchemaMigration(file: MigrationFile): Promise<Migration | null> {
+		const result = await file.getContent()
+		return isSchemaMigration(result) ? result : null
+	}
+}

package/src/SchemaVersionBuilder.ts

@@ -0,0 +1,33 @@
+import { Schema } from '@contember/schema'
+import { emptySchema } from '@contember/schema-utils'
+import { SchemaMigrator } from '@contember/schema-migrations'
+import { MigrationsResolver } from './MigrationsResolver'
+
+export class SchemaVersionBuilder {
+	constructor(
+		private readonly migrationsResolver: MigrationsResolver,
+		private readonly schemaMigrator: SchemaMigrator,
+	) {}
+
+	async buildSchema(targetVersion?: string): Promise<Schema> {
+		return this.buildSchemaAdvanced(emptySchema, version => !targetVersion || version <= targetVersion)
+	}
+
+	async buildSchemaUntil(targetVersion: string): Promise<Schema> {
+		return this.buildSchemaAdvanced(emptySchema, version => version < targetVersion)
+	}
+
+	async continue(schema: Schema, previousVersion: string | null, targetVersion: string): Promise<Schema> {
+		return this.buildSchemaAdvanced(schema, version => version <= targetVersion && version > (previousVersion || ''))
+	}
+
+	public async buildSchemaAdvanced(initialSchema: Schema, condition: (version: string) => boolean): Promise<Schema> {
+		return (await this.migrationsResolver.getSchemaMigrations())
+			.filter(({ version }) => condition(version))
+			.reduce<Schema>(
+				(schema, { modifications, formatVersion }) =>
+					this.schemaMigrator.applyModifications(schema, modifications, formatVersion),
+				initialSchema,
+			)
+	}
+}

package/src/SystemClient.ts

@@ -0,0 +1,150 @@
+import { GraphQLClient } from 'graphql-request'
+import { ExecutedMigration, ExecutedMigrationInfo } from './migrations'
+
+export type MigrateError = {
+	readonly code: MigrateErrorCode
+	readonly migration: string
+	readonly message: string
+}
+
+export enum MigrateErrorCode {
+	MustFollowLatest = 'MUST_FOLLOW_LATEST',
+	AlreadyExecuted = 'ALREADY_EXECUTED',
+	InvalidFormat = 'INVALID_FORMAT',
+	InvalidSchema = 'INVALID_SCHEMA',
+	MigrationFailed = 'MIGRATION_FAILED',
+}
+
+export type MigrateResponse = {
+	readonly ok: boolean
+	readonly errors: MigrateError[]
+}
+
+export class SystemClient {
+	constructor(private readonly apiClient: GraphQLClient) {}
+
+	public static create(baseUrl: string, projectName: string, apiToken: string): SystemClient {
+		const graphqlClient = new GraphQLClient(createSystemUrl(baseUrl, projectName), {
+			headers: {
+				Authorization: `Bearer ${apiToken}`,
+			},
+		})
+		return new SystemClient(graphqlClient)
+	}
+
+	public async migrate(migrations: any[], force = false): Promise<void> {
+		const query = `
+mutation($migrations: [Migration!]!) {
+	migrate: ${force ? 'forceMigrate' : 'migrate'}(migrations: $migrations) {
+		ok
+		errors {
+			code
+			migration
+			message: developerMessage
+		}
+	}
+}
+`
+		const result = (
+			await this.apiClient.request<{
+				migrate: { ok: boolean; errors: { code: MigrateErrorCode; migration: string; message: string }[] }
+			}>(query, {
+				migrations,
+			})
+		).migrate
+		if (!result.ok) {
+			throw result.errors
+		}
+	}
+
+	public async migrationDelete(version: string): Promise<void> {
+		const query = `
+mutation($version: String!) {
+	migrationDelete(migration: $version) {
+		ok
+		error {
+			developerMessage
+		}
+	}
+}
+`
+		const result = (
+			await this.apiClient.request<{
+				migrationDelete: { ok: boolean; error?: { developerMessage: string } }
+			}>(query, {
+				version,
+			})
+		).migrationDelete
+		if (!result.ok) {
+			throw result.error?.developerMessage
+		}
+	}
+
+	public async migrationModify(version: string, modification: Partial<any>): Promise<void> {
+		const query = `
+mutation($version: String!, $modification: MigrationModification!) {
+	migrationModify(migration: $version, modification: $modification) {
+		ok
+		error {
+			developerMessage
+		}
+	}
+}
+`
+		const result = (
+			await this.apiClient.request<{
+				migrationModify: { ok: boolean; error?: { developerMessage: string } }
+			}>(query, {
+				version,
+				modification,
+			})
+		).migrationModify
+		if (!result.ok) {
+			throw result.error?.developerMessage
+		}
+	}
+
+	public async listExecutedMigrations(): Promise<ExecutedMigrationInfo[]> {
+		const query = `query {
+	executedMigrations {
+		name
+		version
+		formatVersion
+		checksum
+		executedAt
+	}
+}`
+		return (
+			await this.apiClient.request<{
+				executedMigrations: ExecutedMigrationInfo[]
+			}>(query, {})
+		).executedMigrations.map(it => ({ ...it, executedAt: new Date(it.executedAt) }))
+	}
+
+	public async getExecutedMigration(version: string): Promise<ExecutedMigration> {
+		const query = `query($version: String!) {
+	executedMigrations(version: $version) {
+		name
+		version
+		formatVersion
+		checksum
+		executedAt
+		modifications
+	}
+}`
+		return (
+			(
+				await this.apiClient.request<{
+					executedMigrations: ExecutedMigration[]
+				}>(query, { version })
+			).executedMigrations.map(it => ({ ...it, executedAt: new Date(it.executedAt) }))[0] || null
+		)
+	}
+}
+
+const createSystemUrl = (baseUrl: string, projectName: string) => {
+	if (baseUrl.endsWith('/')) {
+		baseUrl = baseUrl.substring(0, baseUrl.length - 1)
+	}
+	return baseUrl + '/system/' + projectName
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export {
+	Migration,
+	MigrationDescriber,
+	MigrationInfo,
+	ModificationHandlerFactory,
+	SchemaDiffer,
+	SchemaMigrator,
+	VERSION_LATEST,
+	calculateMigrationChecksum,
+} from '@contember/schema-migrations'
+
+export * from './JsLoader'
+export * from './JsonLoader'
+export * from './MigrationCreator'
+export * from './MigrationExecuteHelper'
+export * from './MigrationFile'
+export * from './MigrationFileLoader'
+export * from './MigrationFilesManager'
+export * from './MigrationParser'
+export * from './migrations'
+export * from './MigrationsResolver'
+export * from './SchemaVersionBuilder'
+export * from './SystemClient'

package/src/migrations.ts

@@ -0,0 +1,157 @@
+import { calculateMigrationChecksum, Migration, MigrationInfo } from '@contember/schema-migrations'
+import { isSchemaMigration, MigrationFile } from './MigrationFile'
+
+export interface ExecutedMigrationInfo extends MigrationInfo {
+	readonly executedAt: Date
+	readonly checksum: string
+}
+
+export interface ExecutedMigration extends Migration {
+	readonly executedAt: Date
+	readonly checksum: string
+}
+
+export enum MigrationState {
+	TO_EXECUTE_OK = 'to_execute_ok',
+	TO_EXECUTE_ERROR = 'to_execute_error',
+	EXECUTED_OK = 'executed_ok',
+	EXECUTED_ERROR = 'executed_error',
+	EXECUTED_MISSING = 'executed_missing',
+}
+
+export interface MigrationStatusBase<S extends MigrationState> {
+	state: S
+	version: string
+	name: string
+}
+
+export interface MigrationToExecuteOkStatus extends MigrationStatusBase<MigrationState.TO_EXECUTE_OK> {
+	localMigration: MigrationFile
+}
+
+interface MigrationToExecuteInvalidStatus extends MigrationStatusBase<MigrationState.TO_EXECUTE_ERROR> {
+	localMigration: MigrationFile
+	errorMessage: string
+}
+
+interface MigrationExecutedOkStatus extends MigrationStatusBase<MigrationState.EXECUTED_OK>{
+	executedMigration: ExecutedMigrationInfo
+	localMigration: MigrationFile
+}
+
+interface MigrationExecutedMissingStatus extends MigrationStatusBase<MigrationState.EXECUTED_MISSING>{
+	executedMigration: ExecutedMigrationInfo
+	errorMessage: string
+}
+
+interface MigrationExecutedErrorStatus extends MigrationStatusBase<MigrationState.EXECUTED_ERROR>{
+	executedMigration: ExecutedMigrationInfo
+	localMigration: MigrationFile
+	errorMessage: string
+}
+
+export type ErrorMigrationStatus =
+	| MigrationToExecuteInvalidStatus
+	| MigrationExecutedMissingStatus
+	| MigrationExecutedErrorStatus
+
+export type AnyMigrationStatus =
+	| ErrorMigrationStatus
+	| MigrationToExecuteOkStatus
+	| MigrationExecutedOkStatus
+
+const isErrorMigrationStatus = (migration: AnyMigrationStatus): migration is ErrorMigrationStatus =>
+	[MigrationState.EXECUTED_ERROR, MigrationState.EXECUTED_MISSING, MigrationState.TO_EXECUTE_ERROR].includes(
+		migration.state,
+	)
+
+export const sortMigrations = <M extends { version: string }>(migrations: M[]): M[] => {
+	return [...migrations].sort((a, b) => a.version.localeCompare(b.version))
+}
+
+export class MigrationsStatusResolver {
+
+	async getMigrationsStatus(
+		executedMigrations: ExecutedMigrationInfo[],
+		localMigrations: MigrationFile[],
+		force: boolean = false,
+	): Promise<{
+		allMigrations: AnyMigrationStatus[]
+		errorMigrations: ErrorMigrationStatus[]
+		migrationsToExecute: MigrationToExecuteOkStatus[]
+	}> {
+		const sortedExecuted = sortMigrations(executedMigrations)
+
+		const allMigrations: AnyMigrationStatus[] = []
+		for (const executed of sortedExecuted) {
+			const localMigration = localMigrations.find(it => it.version === executed.version)
+			if (!localMigration) {
+				allMigrations.push({
+					state: MigrationState.EXECUTED_MISSING,
+					executedMigration: executed,
+					version: executed.version,
+					name: executed.name,
+					errorMessage: `Migration ${executed.name} is missing locally`,
+				})
+				continue
+			}
+			const migrationContent = await localMigration.getContent()
+
+			const localChecksum = !isSchemaMigration(migrationContent) ? null : calculateMigrationChecksum(migrationContent)
+
+			if (localChecksum !== executed.checksum) {
+				allMigrations.push({
+					state: MigrationState.EXECUTED_ERROR,
+					executedMigration: executed,
+					version: executed.version,
+					name: executed.name,
+					localMigration,
+					errorMessage: `Checksum of executed migration "${executed.checksum}" does not match "${localChecksum}"`,
+				})
+				continue
+			}
+			allMigrations.push({
+				state: MigrationState.EXECUTED_OK,
+				executedMigration: executed,
+				version: executed.version,
+				name: executed.name,
+				localMigration,
+			})
+		}
+
+		const latestExecuted = sortedExecuted.length > 0 ? sortedExecuted[sortedExecuted.length - 1] : null
+		for (const localMigration of localMigrations) {
+			if (allMigrations.find(it => it.version === localMigration.version)) {
+				continue
+			}
+
+			if (latestExecuted && latestExecuted.version > localMigration.version) {
+				allMigrations.push({
+					state: MigrationState.TO_EXECUTE_ERROR,
+					localMigration,
+					version: localMigration.version,
+					name: localMigration.name,
+					errorMessage: `Must follow latest executed migration ${latestExecuted.name}`,
+				})
+				continue
+			}
+			allMigrations.push({
+				state: MigrationState.TO_EXECUTE_OK,
+				localMigration,
+				version: localMigration.version,
+				name: localMigration.name,
+			})
+		}
+		const allMigrationsSorted = sortMigrations(allMigrations)
+
+		return {
+			allMigrations: allMigrationsSorted,
+			errorMigrations: allMigrationsSorted.filter(isErrorMigrationStatus),
+			migrationsToExecute: allMigrationsSorted.filter(
+				(it): it is MigrationToExecuteOkStatus =>
+					it.state === MigrationState.TO_EXECUTE_OK || (force && it.state === MigrationState.TO_EXECUTE_ERROR),
+			),
+		}
+	}
+
+}

package/src/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"extends": "../tsconfig.settings.json",
+	"compilerOptions": {
+		"esModuleInterop": true,
+		"outDir": "../dist/src"
+	},
+	"references": [
+		{ "path": "../../engine-common/src" },
+		{ "path": "../../schema/src" },
+		{ "path": "../../schema-migrations/src" },
+		{ "path": "../../schema-utils/src" }
+	]
+}

package/src/utils/assertNever.ts

@@ -0,0 +1,3 @@
+export function assertNever(_: never): never {
+	throw new Error()
+}

package/src/utils/json.ts

@@ -0,0 +1,4 @@
+export type JSONPrimitive = string | number | boolean | null | undefined | unknown
+export type JSONValue = JSONPrimitive | JSONObject | JSONArray
+export type JSONObject = { [member: string]: JSONValue }
+export type JSONArray = JSONValue[]

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+	"files": [],
+	"include": [],
+	"references": [{ "path": "./src" }]
+}

package/tsconfig.settings.json

@@ -0,0 +1,3 @@
+{
+	"extends": "../../tsconfig.settings.json"
+}