@magek/common 0.0.7 → 0.0.8

package/dist/config.d.ts

@@ -61,6 +61,10 @@ export declare class MagekConfig {
     enableSubscriptions: boolean;
     readonly nonExposedGraphQLMetadataKey: Record<string, Array<string>>;
     dispatchedEventsTtl: number;
+    /** Interval in milliseconds between event polling cycles. Default: 1000ms */
+    eventPollingIntervalMs: number;
+    /** Number of events to process per polling cycle. Default: 100 */
+    eventProcessingBatchSize: number;
     traceConfiguration: TraceConfiguration;
     eventStreamConfiguration: EventStreamConfiguration;
     /** Environment variables to set when running the application */

package/dist/config.js

@@ -67,6 +67,10 @@ class MagekConfig {
     nonExposedGraphQLMetadataKey = {};
     // TTL for events stored in dispatched events table. Default to 5 minutes (i.e., 300 seconds).
     dispatchedEventsTtl = 300;
+    /** Interval in milliseconds between event polling cycles. Default: 1000ms */
+    eventPollingIntervalMs = 1000;
+    /** Number of events to process per polling cycle. Default: 100 */
+    eventProcessingBatchSize = 100;
     traceConfiguration = {
         enableTraceNotification: false,
         includeInternal: false,

package/dist/envelope.d.ts

@@ -39,9 +39,17 @@ export interface NonPersistedEventEnvelope extends EventStoreEntryEnvelope {
     createdAt: string;
 }
 export interface EventEnvelope extends NonPersistedEventEnvelope {
+    /** Unique identifier assigned by the event store after persistence. */
     id?: string;
+    /** ISO timestamp when the event was created. */
     createdAt: string;
+    /** ISO timestamp when the event was soft-deleted, if applicable. */
     deletedAt?: string;
+    /**
+     * ISO timestamp when the event was processed by async event processing.
+     * Used for filtering unprocessed events and as an audit marker.
+     */
+    processedAt?: string;
 }
 export interface NonPersistedEntitySnapshotEnvelope extends EventStoreEntryEnvelope {
     kind: 'snapshot';

package/dist/event-store-adapter.d.ts

@@ -10,8 +10,32 @@ export interface EventStoreAdapter {
      * @returns An array of EventEnvelope objects
      */
     rawToEnvelopes(rawEvents: unknown): Array<EventEnvelope>;
+    /**
+     * Converts raw stream data into an array of EventEnvelope objects.
+     *
+     * @param config - The Magek configuration object
+     * @param context - The context from the raw stream
+     * @param dedupEventStream - The deduplicated event stream
+     * @returns An array of EventEnvelope objects
+     */
     rawStreamToEnvelopes(config: MagekConfig, context: unknown, dedupEventStream: EventStream): Array<EventEnvelope>;
+    /**
+     * Deduplicates raw events and returns them as an EventStream.
+     *
+     * @param config - The Magek configuration object
+     * @param rawEvents - The raw events data to deduplicate
+     * @returns A promise that resolves to a deduplicated EventStream
+     */
     dedupEventStream(config: MagekConfig, rawEvents: unknown): Promise<EventStream>;
+    /**
+     * Produces events to an external event stream (e.g., Kafka).
+     *
+     * @param entityName - The name of the entity type
+     * @param entityID - The unique identifier of the entity
+     * @param eventEnvelopes - The array of EventEnvelope objects to produce
+     * @param config - The Magek configuration object
+     * @returns A promise that resolves when events are produced
+     */
     produce(entityName: string, entityID: UUID, eventEnvelopes: Array<EventEnvelope>, config: MagekConfig): Promise<void>;
     /**
      * Retrieves events for a specific entity since a given time
@@ -76,48 +100,79 @@ export interface EventStoreAdapter {
      */
     storeDispatched(eventEnvelope: EventEnvelope, config: MagekConfig): Promise<boolean>;
     /**
-     * Find all events to be removed based on the parameters
+     * Finds all events matching the deletion criteria.
      *
-     * @param config
-     * @param parameters
+     * @param config - The Magek configuration object
+     * @param parameters - The parameters specifying which events to find for deletion
+     * @returns A promise that resolves to an array of EventEnvelopeFromDatabase objects
      */
     findDeletableEvent(config: MagekConfig, parameters: EventDeleteParameters): Promise<Array<EventEnvelopeFromDatabase>>;
     /**
-     * Find all snapshots to be removed based on the parameters
+     * Finds all snapshots matching the deletion criteria.
      *
-     * @param config
-     * @param parameters
+     * @param config - The Magek configuration object
+     * @param parameters - The parameters specifying which snapshots to find for deletion
+     * @returns A promise that resolves to an array of EntitySnapshotEnvelopeFromDatabase objects
      */
     findDeletableSnapshot(config: MagekConfig, parameters: SnapshotDeleteParameters): Promise<Array<EntitySnapshotEnvelopeFromDatabase>>;
     /**
-     * Delete events
+     * Soft-deletes events by marking them with a deletedAt timestamp.
      *
-     * @param config
-     * @param events
+     * @param config - The Magek configuration object
+     * @param events - The array of events to delete
+     * @returns A promise that resolves when the events are deleted
      */
     deleteEvent(config: MagekConfig, events: Array<EventEnvelopeFromDatabase>): Promise<void>;
     /**
-     * Delete snapshots
+     * Soft-deletes snapshots by marking them with a deletedAt timestamp.
      *
-     * @param config
-     * @param snapshots
+     * @param config - The Magek configuration object
+     * @param snapshots - The array of snapshots to delete
+     * @returns A promise that resolves when the snapshots are deleted
      */
     deleteSnapshot(config: MagekConfig, snapshots: Array<EntitySnapshotEnvelopeFromDatabase>): Promise<void>;
     /**
-     * Health check methods for the event store
+     * Health check methods for the event store.
      */
     healthCheck?: {
         /**
-         * Check if the event store is up and running
+         * Checks if the event store is up and running.
+         *
+         * @param config - The Magek configuration object
+         * @returns A promise that resolves to true if the event store is healthy
          */
         isUp(config: MagekConfig): Promise<boolean>;
         /**
-         * Get detailed health information about the event store
+         * Gets detailed health information about the event store.
+         *
+         * @param config - The Magek configuration object
+         * @returns A promise that resolves to health details
          */
         details(config: MagekConfig): Promise<unknown>;
         /**
-         * Get the URLs/endpoints of the event store
+         * Gets the URLs/endpoints of the event store.
+         *
+         * @param config - The Magek configuration object
+         * @returns A promise that resolves to an array of URL strings
          */
         urls(config: MagekConfig): Promise<Array<string>>;
     };
+    /**
+     * Fetches the next batch of unprocessed events.
+     * The adapter manages the cursor internally to track processing position.
+     * Batch size is read from config.eventProcessingBatchSize.
+     *
+     * @param config - The Magek configuration object
+     * @returns A promise that resolves to an array of EventEnvelope objects
+     */
+    fetchUnprocessedEvents?(config: MagekConfig): Promise<Array<EventEnvelope>>;
+    /**
+     * Marks a single event as processed and advances the internal cursor.
+     * Should be called after each event has been successfully dispatched.
+     *
+     * @param config - The Magek configuration object
+     * @param eventId - The ID of the event that was processed
+     * @returns A promise that resolves when the event is marked and cursor is updated
+     */
+    markEventProcessed?(config: MagekConfig, eventId: UUID): Promise<void>;
 }

package/dist/index.d.ts

@@ -1,30 +1,27 @@
-export * from './groups';
-export * from './promises';
-export * from './retrier';
-export * from './instances';
-export * from './run-command';
-export * from './logger';
-export * from './http-service';
 export * from './app';
-export * from './envelope';
 export * from './config';
 export * from './concepts';
-export * from './typelevel';
+export * from './envelope';
 export * from './errors';
 export * from './errors/index';
-export * from './user-app';
+export * from './logger';
 export * from './searcher';
-export * from './graphql-websocket-messages';
-export * from './schedule';
-export * from './data-migration-parameters';
-export * from './super-kind';
-export * from './instrumentation/trace-types';
-export * from './sensor/health-indicator-configuration';
-export * from './internal-info';
-export * from './stream-types';
-export * from './runtime';
 export * from './event-store-adapter';
 export * from './read-model-store-adapter';
 export * from './session-store-adapter';
-export * from './metadata-types';
+export * from './retrier';
 export * from './timestamp-generator';
+export * from './instances';
+export * from './groups';
+export * from './stream-types';
+export * from './typelevel';
+export * from './runtime';
+export * from './user-app';
+export * from './metadata-types';
+export * from './super-kind';
+export * from './schedule';
+export * from './data-migration-parameters';
+export * from './graphql-websocket-messages';
+export * from './http-service';
+export * from './instrumentation/trace-types';
+export * from './sensor/health-indicator-configuration';

package/dist/index.js

@@ -1,33 +1,43 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./groups"), exports);
-tslib_1.__exportStar(require("./promises"), exports);
-tslib_1.__exportStar(require("./retrier"), exports);
-tslib_1.__exportStar(require("./instances"), exports);
-tslib_1.__exportStar(require("./run-command"), exports);
-tslib_1.__exportStar(require("./logger"), exports);
-tslib_1.__exportStar(require("./http-service"), exports);
+// =============================================================================
+// PUBLIC API - Core Framework Types
+// These are the primary exports for framework users building Magek applications
+// =============================================================================
 tslib_1.__exportStar(require("./app"), exports);
-tslib_1.__exportStar(require("./envelope"), exports);
 tslib_1.__exportStar(require("./config"), exports);
 tslib_1.__exportStar(require("./concepts"), exports);
-tslib_1.__exportStar(require("./typelevel"), exports);
+tslib_1.__exportStar(require("./envelope"), exports);
 tslib_1.__exportStar(require("./errors"), exports);
 tslib_1.__exportStar(require("./errors/index"), exports);
-tslib_1.__exportStar(require("./user-app"), exports);
+tslib_1.__exportStar(require("./logger"), exports);
 tslib_1.__exportStar(require("./searcher"), exports);
-tslib_1.__exportStar(require("./graphql-websocket-messages"), exports);
-tslib_1.__exportStar(require("./schedule"), exports);
-tslib_1.__exportStar(require("./data-migration-parameters"), exports);
-tslib_1.__exportStar(require("./super-kind"), exports);
-tslib_1.__exportStar(require("./instrumentation/trace-types"), exports);
-tslib_1.__exportStar(require("./sensor/health-indicator-configuration"), exports);
-tslib_1.__exportStar(require("./internal-info"), exports);
-tslib_1.__exportStar(require("./stream-types"), exports);
-tslib_1.__exportStar(require("./runtime"), exports);
+// =============================================================================
+// ADAPTER DEVELOPMENT
+// Types and utilities for building custom adapters (event stores, read models, etc.)
+// =============================================================================
 tslib_1.__exportStar(require("./event-store-adapter"), exports);
 tslib_1.__exportStar(require("./read-model-store-adapter"), exports);
 tslib_1.__exportStar(require("./session-store-adapter"), exports);
-tslib_1.__exportStar(require("./metadata-types"), exports);
+tslib_1.__exportStar(require("./retrier"), exports);
 tslib_1.__exportStar(require("./timestamp-generator"), exports);
+tslib_1.__exportStar(require("./instances"), exports);
+tslib_1.__exportStar(require("./groups"), exports);
+tslib_1.__exportStar(require("./stream-types"), exports);
+// =============================================================================
+// FRAMEWORK INTERNALS
+// Used by @magek/core, @magek/server, and other framework packages
+// These may change between versions - use with caution in user code
+// =============================================================================
+tslib_1.__exportStar(require("./typelevel"), exports);
+tslib_1.__exportStar(require("./runtime"), exports);
+tslib_1.__exportStar(require("./user-app"), exports);
+tslib_1.__exportStar(require("./metadata-types"), exports);
+tslib_1.__exportStar(require("./super-kind"), exports);
+tslib_1.__exportStar(require("./schedule"), exports);
+tslib_1.__exportStar(require("./data-migration-parameters"), exports);
+tslib_1.__exportStar(require("./graphql-websocket-messages"), exports);
+tslib_1.__exportStar(require("./http-service"), exports);
+tslib_1.__exportStar(require("./instrumentation/trace-types"), exports);
+tslib_1.__exportStar(require("./sensor/health-indicator-configuration"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magek/common",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Contains Magek common helpers used by the core and provider packages",
   "keywords": [
     "framework-common-helpers"
@@ -33,7 +33,7 @@
     "uuid": "^13.0.0"
   },
   "devDependencies": {
-    "@magek/eslint-config": "^0.0.7",
+    "@magek/eslint-config": "^0.0.8",
     "@types/chai": "5.2.3",
     "@types/chai-as-promised": "8.0.2",
     "@types/mocha": "10.0.10",

package/dist/internal-info.d.ts

@@ -1,2 +0,0 @@
-export declare const MAGEK_LOCAL_PORT = "INTERNAL_LOCAL_PORT";
-export declare const localPort: () => string;

package/dist/internal-info.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.localPort = exports.MAGEK_LOCAL_PORT = void 0;
-exports.MAGEK_LOCAL_PORT = 'INTERNAL_LOCAL_PORT';
-const localPort = () => process.env[exports.MAGEK_LOCAL_PORT] || '3000';
-exports.localPort = localPort;

package/dist/promises.d.ts

@@ -1,25 +0,0 @@
-export declare class Promises {
-    /**
-     * Waits until all the passed promise-like values are settled, no matter if they were fulfilled or rejected.
-     * If some rejected were found, an array with all the rejected promises is thrown.
-     * If all were fulfilled, an array of PromiseFulfilledResult is returned
-     * @param values Array of promise-like values to be wait for
-     * @throws an array of PromiseRejectedResult with all the rejected promises, if any
-     *
-     * Comparison with other similar Promise methods:
-     * - `Promise.all`: This has an "all-or-nothing" behavior. As long as one of the promises is rejected, the result is
-     * rejected. More importantly, **it does not wait for al the promises to finish**, which could lead to undesired behaviors
-     * - `Promise.allSettled`: This method waits for all the promises to finish and then returns an array of results. Some
-     * of them will be fulfilled and some rejected. More importantly, **it never throws an error**, which could lead to
-     * unexpected consequences. For example if you do "await Promise.allSettle(...)" expecting it to throw if some of them
-     * failed, you won't get that.
-     *
-     * In brief, `Promises.allSettledAndFulfilled` behaves exactly the same way as `Promise.allSettle` but it throws with
-     * an array of the failed promises, only if there are any.
-     */
-    static allSettledAndFulfilled<TValue>(values: Iterable<TValue>): ReturnType<PromiseConstructor['allSettled']>;
-}
-export declare class PromisesError extends Error {
-    readonly failedReasons: Array<unknown>;
-    constructor(rejectedResults: Array<PromiseRejectedResult>);
-}

package/dist/promises.js

@@ -1,43 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PromisesError = exports.Promises = void 0;
-class Promises {
-    /**
-     * Waits until all the passed promise-like values are settled, no matter if they were fulfilled or rejected.
-     * If some rejected were found, an array with all the rejected promises is thrown.
-     * If all were fulfilled, an array of PromiseFulfilledResult is returned
-     * @param values Array of promise-like values to be wait for
-     * @throws an array of PromiseRejectedResult with all the rejected promises, if any
-     *
-     * Comparison with other similar Promise methods:
-     * - `Promise.all`: This has an "all-or-nothing" behavior. As long as one of the promises is rejected, the result is
-     * rejected. More importantly, **it does not wait for al the promises to finish**, which could lead to undesired behaviors
-     * - `Promise.allSettled`: This method waits for all the promises to finish and then returns an array of results. Some
-     * of them will be fulfilled and some rejected. More importantly, **it never throws an error**, which could lead to
-     * unexpected consequences. For example if you do "await Promise.allSettle(...)" expecting it to throw if some of them
-     * failed, you won't get that.
-     *
-     * In brief, `Promises.allSettledAndFulfilled` behaves exactly the same way as `Promise.allSettle` but it throws with
-     * an array of the failed promises, only if there are any.
-     */
-    static async allSettledAndFulfilled(values) {
-        const results = await Promise.allSettled(values); // Promise.allSettled never throws
-        // Get all the failed promises
-        const failed = results.filter((result) => result.status === 'rejected');
-        // Throw if we found any failed ones
-        if (failed.length > 0) {
-            throw new PromisesError(failed);
-        }
-        return results;
-    }
-}
-exports.Promises = Promises;
-class PromisesError extends Error {
-    failedReasons;
-    constructor(rejectedResults) {
-        const reasons = rejectedResults.map((res) => res.reason);
-        super(reasons.join('. '));
-        this.failedReasons = reasons;
-    }
-}
-exports.PromisesError = PromisesError;

package/dist/run-command.d.ts

@@ -1,5 +0,0 @@
-import { ChildProcessWithoutNullStreams } from 'child_process';
-/** Spawn a CLI command and optionally printing the logs and error messages */
-export declare function runCommandAsync(path: string, command: string, ignoreLogs?: boolean): ChildProcessWithoutNullStreams;
-/** Synchronously run a CLI command and return the stdout, optionally printing the logs and error messages */
-export declare function runCommand(path: string, command: string, ignoreLogs?: boolean): Promise<string>;

package/dist/run-command.js

@@ -1,48 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runCommandAsync = runCommandAsync;
-exports.runCommand = runCommand;
-const child_process_1 = require("child_process");
-/** Spawn a CLI command and optionally printing the logs and error messages */
-function runCommandAsync(path, command, ignoreLogs = false) {
-    // Split the command into an array of arguments
-    const args = command.split(' ');
-    // Use the first argument as the command name
-    const subprocess = (0, child_process_1.spawn)(args[0], args.slice(1), {
-        cwd: path,
-        stdio: 'pipe',
-    });
-    if (!ignoreLogs) {
-        subprocess.stdout.on('data', (data) => {
-            console.log(data.toString());
-        });
-        subprocess.stderr.on('data', (data) => {
-            console.error(data.toString());
-        });
-    }
-    return subprocess;
-}
-/** Synchronously run a CLI command and return the stdout, optionally printing the logs and error messages */
-function runCommand(path, command, ignoreLogs = false) {
-    return new Promise((resolve, reject) => {
-        const subprocess = runCommandAsync(path, command, ignoreLogs);
-        let stdout = '';
-        let stderr = '';
-        if (subprocess) {
-            subprocess.stdout.on('data', (data) => {
-                stdout += data.toString();
-            });
-            subprocess.stderr.on('data', (data) => {
-                stderr += data.toString();
-            });
-            subprocess.on('close', (code) => {
-                if (code === 0) {
-                    resolve(stdout);
-                }
-                else {
-                    reject(stderr);
-                }
-            });
-        }
-    });
-}