node-cqrs 1.0.0-rc.8 → 1.0.0

package/src/sqlite/SqliteEventLocker.ts

@@ -1,137 +0,0 @@
-import { Database, Statement } from 'better-sqlite3';
-import { IContainer, IEvent, IEventLocker } from '../interfaces';
-import { getEventId } from './utils';
-import { viewLockTableInit, eventLockTableInit } from './queries';
-import { SqliteViewLockerParams } from './SqliteViewLocker';
-import { SqliteProjectionDataParams } from './SqliteProjectionDataParams';
-import { AbstractSqliteAccessor } from './AbstractSqliteAccessor';
-
-export type SqliteEventLockerParams =
-	SqliteProjectionDataParams
-	& Pick<SqliteViewLockerParams, 'viewLockTableName'>
-	& {
-
-		/**
-		 * (Optional) SQLite table name where event locks are stored
-		 *
-		 * @default "tbl_event_lock"
-		 */
-		eventLockTableName?: string;
-
-		/**
-		 * (Optional) Time-to-live (TTL) duration in milliseconds
-		 * for which an event remains in the "processing" state until released.
-		 *
-		 * @default 15_000
-		 */
-		eventLockTtl?: number;
-	};
-
-export class SqliteEventLocker extends AbstractSqliteAccessor implements IEventLocker {
-
-	#projectionName: string;
-	#schemaVersion: string;
-	#viewLockTableName: string;
-	#eventLockTableName: string;
-	#eventLockTtl: number;
-
-	#upsertLastEventQuery!: Statement<[string, string, string], void>;
-	#getLastEventQuery!: Statement<[string, string], { last_event: string }>;
-	#lockEventQuery!: Statement<[string, string, Buffer], void>;
-	#finalizeEventLockQuery!: Statement<[string, string, Buffer], void>;
-
-	constructor(o: Pick<IContainer, 'viewModelSqliteDb' | 'viewModelSqliteDbFactory'> & SqliteEventLockerParams) {
-		super(o);
-
-		if (!o.projectionName)
-			throw new TypeError('projectionName argument required');
-		if (!o.schemaVersion)
-			throw new TypeError('schemaVersion argument required');
-
-		this.#projectionName = o.projectionName;
-		this.#schemaVersion = o.schemaVersion;
-		this.#viewLockTableName = o.viewLockTableName ?? 'tbl_view_lock';
-		this.#eventLockTableName = o.eventLockTableName ?? 'tbl_event_lock';
-		this.#eventLockTtl = o.eventLockTtl ?? 15_000;
-	}
-
-	protected initialize(db: Database) {
-		db.exec(viewLockTableInit(this.#viewLockTableName));
-		db.exec(eventLockTableInit(this.#eventLockTableName));
-
-		this.#upsertLastEventQuery = db.prepare(`
-			INSERT INTO ${this.#viewLockTableName} (projection_name, schema_version, last_event)
-			VALUES (?, ?, ?)
-			ON CONFLICT (projection_name, schema_version)
-			DO UPDATE SET
-				last_event = excluded.last_event
-		`);
-
-		this.#getLastEventQuery = db.prepare(`
-			SELECT
-				last_event
-			FROM ${this.#viewLockTableName}
-			WHERE
-				projection_name = ?
-				AND schema_version =?
-		`);
-
-		this.#lockEventQuery = db.prepare(`
-			INSERT INTO ${this.#eventLockTableName} (projection_name, schema_version, event_id)
-			VALUES (?, ?, ?)
-			ON CONFLICT (projection_name, schema_version, event_id)
-			DO UPDATE SET
-				processing_at = cast(strftime('%f', 'now') * 1000 as INTEGER)
-			WHERE
-				processed_at IS NULL
-				AND processing_at <= cast(strftime('%f', 'now') * 1000 as INTEGER) - ${this.#eventLockTtl}
-		`);
-
-		this.#finalizeEventLockQuery = db.prepare(`
-			UPDATE ${this.#eventLockTableName}
-			SET
-				processed_at = (cast(strftime('%f', 'now') * 1000 as INTEGER))
-			WHERE
-				projection_name = ?
-				AND schema_version = ?
-				AND event_id = ?
-				AND processed_at IS NULL
-		`);
-	}
-
-	async tryMarkAsProjecting(event: IEvent<any>) {
-		await this.assertConnection();
-
-		const eventId = getEventId(event);
-
-		const r = this.#lockEventQuery.run(this.#projectionName, this.#schemaVersion, eventId);
-
-		return r.changes !== 0;
-	}
-
-	async markAsProjected(event: IEvent<any>) {
-		await this.assertConnection();
-
-		const eventId = getEventId(event);
-
-		const transaction = this.db!.transaction(() => {
-			const updateResult = this.#finalizeEventLockQuery.run(this.#projectionName, this.#schemaVersion, eventId);
-			if (updateResult.changes === 0)
-				throw new Error(`Event ${event.id} could not be marked as processed`);
-
-			this.#upsertLastEventQuery.run(this.#projectionName, this.#schemaVersion, JSON.stringify(event));
-		});
-
-		transaction();
-	}
-
-	async getLastEvent(): Promise<IEvent<any> | undefined> {
-		await this.assertConnection();
-
-		const viewInfoRecord = this.#getLastEventQuery.get(this.#projectionName, this.#schemaVersion);
-		if (!viewInfoRecord?.last_event)
-			return undefined;
-
-		return JSON.parse(viewInfoRecord.last_event);
-	}
-}

package/src/sqlite/SqliteObjectStorage.ts

@@ -1,142 +0,0 @@
-import { Statement, Database } from 'better-sqlite3';
-import { guid } from './utils';
-import { IContainer, IObjectStorage } from '../interfaces';
-import { AbstractSqliteAccessor } from './AbstractSqliteAccessor';
-
-export class SqliteObjectStorage<TRecord> extends AbstractSqliteAccessor implements IObjectStorage<TRecord> {
-
-	#tableName: string;
-	#getQuery!: Statement<[Buffer], { data: string, version: number }>;
-	#insertQuery!: Statement<[Buffer, string], void>;
-	#updateByIdAndVersionQuery!: Statement<[string, Buffer, number], void>;
-	#deleteQuery!: Statement<[Buffer], void>;
-
-	constructor(o: Pick<IContainer, 'viewModelSqliteDb' | 'viewModelSqliteDbFactory'> & {
-		tableName: string
-	}) {
-		super(o);
-
-		this.#tableName = o.tableName;
-	}
-
-	protected initialize(db: Database) {
-		db.exec(`CREATE TABLE IF NOT EXISTS ${this.#tableName} (
-			id BLOB PRIMARY KEY,
-			version INTEGER DEFAULT 1,
-			data TEXT NOT NULL
-		);`);
-
-		this.#getQuery = db.prepare(`
-			SELECT data, version
-			FROM ${this.#tableName}
-			WHERE id = ?
-		`);
-
-		this.#insertQuery = db.prepare(`
-			INSERT INTO ${this.#tableName} (id, data)
-			VALUES (?, ?)
-		`);
-
-		this.#updateByIdAndVersionQuery = db.prepare(`
-			UPDATE ${this.#tableName}
-			SET
-				data = ?,
-				version = version + 1
-			WHERE
-				id = ?
-				AND version = ?
-		`);
-
-		this.#deleteQuery = db.prepare(`
-			DELETE FROM ${this.#tableName}
-			WHERE id = ?
-		`);
-	}
-
-	async get(id: string): Promise<TRecord | undefined> {
-		if (typeof id !== 'string' || !id.length)
-			throw new TypeError('id argument must be a non-empty String');
-
-		await this.assertConnection();
-
-		const r = this.#getQuery.get(guid(id));
-		if (!r)
-			return undefined;
-
-		return JSON.parse(r.data);
-	}
-
-	getSync(id: string): TRecord | undefined {
-		if (typeof id !== 'string' || !id.length)
-			throw new TypeError('id argument must be a non-empty String');
-
-		const r = this.#getQuery.get(guid(id));
-		if (!r)
-			return undefined;
-
-		return JSON.parse(r.data);
-	}
-
-	async create(id: string, data: TRecord) {
-		if (typeof id !== 'string' || !id.length)
-			throw new TypeError('id argument must be a non-empty String');
-
-		await this.assertConnection();
-
-		const r = this.#insertQuery.run(guid(id), JSON.stringify(data));
-		if (r.changes !== 1)
-			throw new Error(`Record '${id}' could not be created`);
-	}
-
-	async update(id: string, update: (r: TRecord) => TRecord) {
-		if (typeof id !== 'string' || !id.length)
-			throw new TypeError('id argument must be a non-empty String');
-		if (typeof update !== 'function')
-			throw new TypeError('update argument must be a Function');
-
-		await this.assertConnection();
-
-		const gid = guid(id);
-		const record = this.#getQuery.get(gid);
-		if (!record)
-			throw new Error(`Record '${id}' does not exist`);
-
-		const data = JSON.parse(record.data);
-		const updatedData = update(data);
-		const updatedJson = JSON.stringify(updatedData);
-
-		// Version check is implemented to ensure the record isn't modified by another process.
-		// A conflict resolution strategy could potentially be passed as an option to this method,
-		// but for now, conflict resolution should happen outside this class.
-		const r = this.#updateByIdAndVersionQuery.run(updatedJson, gid, record.version);
-		if (r.changes !== 1)
-			throw new Error(`Record '${id}' could not be updated`);
-	}
-
-	async updateEnforcingNew(id: string, update: (r?: TRecord) => TRecord) {
-		if (typeof id !== 'string' || !id.length)
-			throw new TypeError('id argument must be a non-empty String');
-		if (typeof update !== 'function')
-			throw new TypeError('update argument must be a Function');
-
-		await this.assertConnection();
-
-		// Due to better-sqlite3 sync nature,
-		// it's safe to get then modify within this process
-		const record = this.#getQuery.get(guid(id));
-		if (record)
-			this.update(id, update);
-		else
-			this.create(id, update());
-	}
-
-	async delete(id: string): Promise<boolean> {
-		if (typeof id !== 'string' || !id.length)
-			throw new TypeError('id argument must be a non-empty String');
-
-		await this.assertConnection();
-
-		const r = this.#deleteQuery.run(guid(id));
-		return r.changes === 1;
-	}
-}

package/src/sqlite/SqliteObjectView.ts

@@ -1,58 +0,0 @@
-import { AbstractSqliteView } from './AbstractSqliteView';
-import { IObjectStorage, IEventLocker } from '../interfaces';
-import { SqliteObjectStorage } from './SqliteObjectStorage';
-import { Database } from 'better-sqlite3';
-
-export class SqliteObjectView<TRecord> extends AbstractSqliteView implements IObjectStorage<TRecord>, IEventLocker {
-
-	#sqliteObjectStorage: SqliteObjectStorage<TRecord>;
-
-	constructor(options: ConstructorParameters<typeof AbstractSqliteView>[0] & {
-		tableNamePrefix: string
-	}) {
-		if (typeof options.tableNamePrefix !== 'string' || !options.tableNamePrefix.length)
-			throw new TypeError('tableNamePrefix argument must be a non-empty String');
-		if (typeof options.schemaVersion !== 'string' || !options.schemaVersion.length)
-			throw new TypeError('schemaVersion argument must be a non-empty String');
-
-		super(options);
-
-		this.#sqliteObjectStorage = new SqliteObjectStorage<TRecord>({
-			viewModelSqliteDb: options.viewModelSqliteDb,
-			viewModelSqliteDbFactory: options.viewModelSqliteDbFactory,
-			tableName: `${options.tableNamePrefix}_${options.schemaVersion}`
-		});
-	}
-
-	// eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
-	protected initialize(db: Database): Promise<void> | void {
-		// No need to initialize the table here, it's done in SqliteObjectStorage
-	}
-
-	async get(id: string): Promise<TRecord | undefined> {
-		if (!this.ready)
-			await this.once('ready');
-
-		return this.#sqliteObjectStorage.get(id);
-	}
-
-	getSync(id: string) {
-		return this.#sqliteObjectStorage.getSync(id);
-	}
-
-	async create(id: string, data: TRecord) {
-		await this.#sqliteObjectStorage.create(id, data);
-	}
-
-	async update(id: string, update: (r: TRecord) => TRecord) {
-		await this.#sqliteObjectStorage.update(id, update);
-	}
-
-	async updateEnforcingNew(id: string, update: (r?: TRecord) => TRecord) {
-		await this.#sqliteObjectStorage.updateEnforcingNew(id, update);
-	}
-
-	async delete(id: string): Promise<boolean> {
-		return this.#sqliteObjectStorage.delete(id);
-	}
-}

package/src/sqlite/SqliteProjectionDataParams.ts

@@ -1,16 +0,0 @@
-export type SqliteProjectionDataParams = {
-
-	/**
-	 * Unique identifier for the projection, used with the schema version to distinguish data ownership.
-	 */
-	projectionName: string;
-
-	/**
-	 * The version of the schema used for data produced by the projection.
-	 * When the projection's output format changes, this version should be incremented.
-	 * A version change indicates that previously stored data is obsolete and must be rebuilt.
-	 *
-	 * @example "20250519", "1.0.0"
-	 */
-	schemaVersion: string;
-}

package/src/sqlite/SqliteViewLocker.ts

@@ -1,167 +0,0 @@
-import { Database, Statement } from 'better-sqlite3';
-import { IContainer, ILogger, IViewLocker } from '../interfaces';
-import { Deferred } from '../utils';
-import { promisify } from 'util';
-import { viewLockTableInit } from './queries';
-import { SqliteProjectionDataParams } from './SqliteProjectionDataParams';
-import { AbstractSqliteAccessor } from './AbstractSqliteAccessor';
-const delay = promisify(setTimeout);
-
-export type SqliteViewLockerParams = SqliteProjectionDataParams & {
-
-	/**
-	 * (Optional) SQLite table name where event locks along with the latest event are stored
-	 *
-	 * @default "tbl_view_lock"
-	 */
-	viewLockTableName?: string;
-
-	/**
-	 * (Optional) Time-to-live (TTL) duration (in milliseconds) for which a view remains locked
-	 *
-	 * @default 120_000
-	 */
-	viewLockTtl?: number;
-};
-
-export class SqliteViewLocker extends AbstractSqliteAccessor implements IViewLocker {
-
-	#projectionName: string;
-	#schemaVersion: string;
-
-	#viewLockTableName: string;
-	#viewLockTtl: number;
-	#logger: ILogger | undefined;
-
-	#upsertTableLockQuery!: Statement<[string, string, number], void>;
-	#updateTableLockQuery!: Statement<[number, string, string], void>;
-	#removeTableLockQuery!: Statement<[string, string], void>;
-
-	#lockMarker: Deferred<void> | undefined;
-	#lockProlongationTimeout: NodeJS.Timeout | undefined;
-
-	constructor(o: Partial<Pick<IContainer, 'viewModelSqliteDb' | 'viewModelSqliteDbFactory' | 'logger'>>
-		& SqliteViewLockerParams) {
-		super(o);
-
-		if (!o.projectionName)
-			throw new TypeError('projectionName argument required');
-		if (!o.schemaVersion)
-			throw new TypeError('schemaVersion argument required');
-
-		this.#projectionName = o.projectionName;
-		this.#schemaVersion = o.schemaVersion;
-
-		this.#viewLockTableName = o.viewLockTableName ?? 'tbl_view_lock';
-		this.#viewLockTtl = o.viewLockTtl ?? 120_000;
-		this.#logger = o.logger && 'child' in o.logger ?
-			o.logger.child({ service: this.constructor.name }) :
-			o.logger;
-	}
-
-	protected initialize(db: Database) {
-		db.exec(viewLockTableInit(this.#viewLockTableName));
-
-		this.#upsertTableLockQuery = db.prepare(`
-			INSERT INTO ${this.#viewLockTableName} (projection_name, schema_version, locked_till)
-			VALUES (?, ?, ?)
-			ON CONFLICT (projection_name, schema_version)
-			DO UPDATE SET
-				locked_till = excluded.locked_till
-			WHERE
-				locked_till IS NULL
-				OR locked_till < excluded.locked_till
-		`);
-
-		this.#updateTableLockQuery = db.prepare(`
-			UPDATE ${this.#viewLockTableName}
-			SET
-				locked_till = ?
-			WHERE
-				projection_name = ?
-				AND schema_version = ?
-				AND locked_till IS NOT NULL
-		`);
-
-		this.#removeTableLockQuery = db.prepare(`
-			UPDATE ${this.#viewLockTableName}
-			SET
-				locked_till = NULL
-			WHERE
-				projection_name = ?
-				AND schema_version = ?
-				AND locked_till IS NOT NULL
-		`);
-	}
-
-	get ready(): boolean {
-		return !this.#lockMarker;
-	}
-
-	async lock() {
-		this.#lockMarker = new Deferred();
-
-		await this.assertConnection();
-
-		let lockAcquired = false;
-		while (!lockAcquired) {
-			const lockedTill = Date.now() + this.#viewLockTtl;
-			const upsertResult = this.#upsertTableLockQuery.run(this.#projectionName, this.#schemaVersion, lockedTill);
-
-			lockAcquired = upsertResult.changes === 1;
-			if (!lockAcquired) {
-				this.#logger?.debug(`"${this.#projectionName}" is locked by another process`);
-				await delay(this.#viewLockTtl / 2);
-			}
-		}
-
-		this.#logger?.debug(`"${this.#projectionName}" lock obtained for ${this.#viewLockTtl}s`);
-
-		this.scheduleLockProlongation();
-
-		return true;
-	}
-
-	private scheduleLockProlongation() {
-		const ms = this.#viewLockTtl / 2;
-
-		this.#lockProlongationTimeout = setTimeout(() => this.prolongLock(), ms);
-		this.#lockProlongationTimeout.unref();
-
-		this.#logger?.debug(`"${this.#projectionName}" lock refresh scheduled in ${ms} ms`);
-	}
-
-	private cancelLockProlongation() {
-		clearTimeout(this.#lockProlongationTimeout);
-		this.#logger?.debug(`"${this.#projectionName}" lock refresh canceled`);
-	}
-
-	private prolongLock() {
-		const lockedTill = Date.now() + this.#viewLockTtl;
-		const r = this.#updateTableLockQuery.run(lockedTill, this.#projectionName, this.#schemaVersion);
-		if (r.changes !== 1)
-			throw new Error(`"${this.#projectionName}" lock could not be prolonged`);
-
-		this.#logger?.debug(`"${this.#projectionName}" lock prolonged for ${this.#viewLockTtl}s`);
-	}
-
-	unlock() {
-		this.#lockMarker?.resolve();
-		this.#lockMarker = undefined;
-
-		this.cancelLockProlongation();
-
-		const updateResult = this.#removeTableLockQuery.run(this.#projectionName, this.#schemaVersion);
-		if (updateResult.changes === 1)
-			this.#logger?.debug(`"${this.#projectionName}" lock released`);
-		else
-			this.#logger?.warn(`"${this.#projectionName}" lock didn't exist`);
-	}
-
-	once(event: 'ready'): Promise<void> {
-		if (event !== 'ready')
-			throw new TypeError(`Unexpected event: ${event}`);
-
-		return this.#lockMarker?.promise ?? Promise.resolve();
-	}
-}

package/src/sqlite/index.ts

@@ -1,8 +0,0 @@
-export * from './AbstractSqliteAccessor';
-export * from './AbstractSqliteObjectProjection';
-export * from './AbstractSqliteView';
-export * from './SqliteEventLocker';
-export * from './SqliteObjectStorage';
-export * from './SqliteObjectView';
-export * from './SqliteViewLocker';
-export * from './utils';

package/src/sqlite/queries/eventLockTableInit.ts

@@ -1,10 +0,0 @@
-export const eventLockTableInit = (eventLockTableName: string) => `
-	CREATE TABLE IF NOT EXISTS ${eventLockTableName} (
-		projection_name TEXT NOT NULL,
-		schema_version TEXT NOT NULL,
-		event_id BLOB NOT NULL,
-		processing_at INTEGER NOT NULL DEFAULT (cast(strftime('%f', 'now') * 1000 as INTEGER)),
-		processed_at INTEGER,
-		PRIMARY KEY (projection_name, schema_version, event_id)
-	);
-`;

package/src/sqlite/queries/index.ts

@@ -1,2 +0,0 @@
-export * from './eventLockTableInit';
-export * from './viewLockTableInit';

package/src/sqlite/queries/viewLockTableInit.ts

@@ -1,9 +0,0 @@
-export const viewLockTableInit = (viewLockTableName: string): string => `
-	CREATE TABLE IF NOT EXISTS ${viewLockTableName} (
-		projection_name TEXT NOT NULL,
-		schema_version TEXT NOT NULL,
-		locked_till INTEGER,
-		last_event TEXT,
-		PRIMARY KEY (projection_name, schema_version)
-	);
-`;

package/src/sqlite/utils/getEventId.ts

@@ -1,8 +0,0 @@
-import { IEvent } from '../../interfaces';
-import { guid } from './guid';
-import md5 = require('md5');
-
-/**
- * Get assigned or generate new event ID from event content
- */
-export const getEventId = (event: IEvent): Buffer => guid(event.id ?? md5(JSON.stringify(event)));

package/src/sqlite/utils/guid.ts

@@ -1,4 +0,0 @@
-/**
- * Convert Guid to Buffer for storing in Sqlite BLOB
- */
-export const guid = (str: string) => Buffer.from(str.replaceAll('-', ''), 'hex');

package/src/sqlite/utils/index.ts

@@ -1,2 +0,0 @@
-export * from './guid';
-export * from './getEventId';

package/src/utils/Deferred.ts

@@ -1,41 +0,0 @@
-/**
- * Deferred promise that must be resolved from outside
- */
-export class Deferred<TDeferredValue> {
-
-	readonly promise: Promise<TDeferredValue | void>;
-
-	get resolved() {
-		return this.#resolved;
-	}
-
-	get rejected() {
-		return this.#rejected;
-	}
-
-	get settled() {
-		return this.#resolved || this.#rejected;
-	}
-
-	#resolve!: (value?: TDeferredValue | PromiseLike<TDeferredValue>) => void;
-	#resolved: boolean = false;
-	#reject!: (reason?: any) => void;
-	#rejected: boolean = false;
-
-	constructor() {
-		this.promise = new Promise<TDeferredValue | void>((resolve, reject) => {
-			this.#resolve = resolve;
-			this.#reject = reject;
-		});
-	}
-
-	resolve(value?: TDeferredValue) {
-		this.#resolve(value);
-		this.#resolved = true;
-	}
-
-	reject(reason?: any) {
-		this.#reject(reason);
-		this.#rejected = true;
-	}
-}

package/src/utils/Lock.ts

@@ -1,53 +0,0 @@
-import { Deferred } from './Deferred';
-
-/**
- * Provides a simple asynchronous lock mechanism.
- * Useful for ensuring that only one asynchronous operation proceeds at a time
- * for a specific resource or section of code.
- */
-export class Lock {
-
-	#deferred?: Deferred<void>;
-
-	get isLocked(): boolean {
-		return !(this.#deferred?.settled ?? true);
-	}
-
-	/**
-	 * Wait until lock is released, then acquire it
-	 */
-	async acquire(): Promise<void> {
-		// the below code cannot be replaced with `await this.unblocked()`
-		// since check of `isLocked` and `this.#deferred` assignment should happen within 1 callback
-		while (this.isLocked)
-			await this.#deferred?.promise;
-
-		this.#deferred = new Deferred();
-	}
-
-	/**
-	 * Returns a promise that is resolved once lock is released
-	 */
-	async unblocked(): Promise<void> {
-		while (this.isLocked)
-			await this.#deferred?.promise;
-	}
-
-	release(): void {
-		this.#deferred?.resolve();
-		this.#deferred = undefined;
-	}
-
-	/**
-	 * Execute callback with lock acquired, then release lock
-	 */
-	async runLocked(callback: () => Promise<void>) {
-		try {
-			await this.acquire();
-			await callback();
-		}
-		finally {
-			this.release();
-		}
-	}
-}

package/src/utils/delay.ts

@@ -1,8 +0,0 @@
-/**
- * Returns a promise that resolves after the specified number of milliseconds.
- * The internal timeout is unref'd to avoid blocking Node.js process termination.
- */
-export const delay = (ms: number) => new Promise<void>(resolve => {
-	const t = setTimeout(resolve, ms);
-	t.unref();
-});

package/src/utils/getClassName.ts

@@ -1,6 +0,0 @@
-/**
- * Get instance class name
- */
-export function getClassName(instance: object): string {
-	return Object.getPrototypeOf(instance).constructor.name;
-}