@magek/core 0.0.7 → 0.0.9

package/dist/decorators/field-metadata-reader.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildClassMetadataFromFields = buildClassMetadataFromFields;
 const decorator_types_1 = require("./decorator-types");
 const read_model_1 = require("./read-model");
+const returns_1 = require("./returns");
 /**
  * Extract TypeMetadata from a @field() decorator's metadata
  */
@@ -200,6 +201,16 @@ function buildClassMetadataFromFields(classType, contextMetadata) {
     }));
     // Get getter methods (for @calculatedField)
     const methods = getAllGetters(classType, contextMetadata);
+    // Check for @returns decorated handle method
+    const handleReturnType = (0, returns_1.getReturnTypeMetadata)(contextMetadata, 'handle');
+    if (handleReturnType) {
+        // Add handle method with its return type to methods array
+        methods.push({
+            name: 'handle',
+            typeInfo: handleReturnType,
+            dependencies: [],
+        });
+    }
     return {
         name: classType.name,
         type: classType,

package/dist/decorators/index.d.ts

@@ -10,6 +10,7 @@ export * from './global-error-handler';
 export * from './notification';
 export * from './projects';
 export * from './read-model';
+export * from './returns';
 export * from './role';
 export * from './scheduled-command';
 export * from './schema-migration';

package/dist/decorators/index.js

@@ -12,6 +12,7 @@ tslib_1.__exportStar(require("./global-error-handler"), exports);
 tslib_1.__exportStar(require("./notification"), exports);
 tslib_1.__exportStar(require("./projects"), exports);
 tslib_1.__exportStar(require("./read-model"), exports);
+tslib_1.__exportStar(require("./returns"), exports);
 tslib_1.__exportStar(require("./role"), exports);
 tslib_1.__exportStar(require("./scheduled-command"), exports);
 tslib_1.__exportStar(require("./schema-migration"), exports);

package/dist/decorators/returns.d.ts

@@ -0,0 +1,37 @@
+import { TypeFunction, TypeMetadata } from '@magek/common';
+import { MethodDecoratorContext, DecoratorMetadataObject } from './decorator-types';
+/** Symbol used to store return type metadata in decorator context.metadata */
+export declare const RETURNS_METADATA_KEY: unique symbol;
+/** Metadata stored for each method's return type */
+export interface ReturnsMetadata {
+    methodName: string;
+    typeFunction: TypeFunction;
+}
+/**
+ * Get the return type metadata for a method from decorator metadata.
+ *
+ * @param contextMetadata - The context.metadata from a class decorator
+ * @param methodName - The name of the method to get return type for
+ */
+export declare function getReturnTypeMetadata(contextMetadata: DecoratorMetadataObject | undefined, methodName: string): TypeMetadata | undefined;
+/**
+ * @returns() decorator for explicit return type declaration on methods.
+ *
+ * Uses TC39 Stage 3 decorators to capture return type metadata that is used
+ * for GraphQL schema generation. The type specified should be the GraphQL
+ * return type (not wrapped in Promise).
+ *
+ * Usage:
+ *   @returns(type => UUID)
+ *   public static async handle(...): Promise<UUID> { ... }
+ *
+ *   @returns(type => String)
+ *   public static async handle(...): Promise<string> { ... }
+ *
+ *   @returns(type => [CartItem])
+ *   public static async handle(...): Promise<CartItem[]> { ... }
+ */
+export declare function returns(typeFunction: TypeFunction): MethodDecorator;
+/** Type for the returns decorator */
+type MethodDecorator = (target: unknown, context: MethodDecoratorContext) => void;
+export {};

package/dist/decorators/returns.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RETURNS_METADATA_KEY = void 0;
+exports.getReturnTypeMetadata = getReturnTypeMetadata;
+exports.returns = returns;
+/** Symbol used to store return type metadata in decorator context.metadata */
+exports.RETURNS_METADATA_KEY = Symbol.for('magek:returns');
+/**
+ * Analyze a type and convert it to TypeMetadata for return types.
+ * This returns the GraphQL-compatible type directly (not wrapped in Promise).
+ */
+function analyzeReturnType(targetType) {
+    // Handle primitives
+    if (targetType === String) {
+        return {
+            name: 'string',
+            typeGroup: 'String',
+            typeName: 'String',
+            parameters: [],
+            isNullable: false,
+            isGetAccessor: false,
+            type: String,
+        };
+    }
+    if (targetType === Number) {
+        return {
+            name: 'number',
+            typeGroup: 'Number',
+            typeName: 'Number',
+            parameters: [],
+            isNullable: false,
+            isGetAccessor: false,
+            type: Number,
+        };
+    }
+    if (targetType === Boolean) {
+        return {
+            name: 'boolean',
+            typeGroup: 'Boolean',
+            typeName: 'Boolean',
+            parameters: [],
+            isNullable: false,
+            isGetAccessor: false,
+            type: Boolean,
+        };
+    }
+    // Handle void - return never to signal void return
+    if (targetType === undefined || targetType === null) {
+        return {
+            name: 'never',
+            typeGroup: 'Other',
+            typeName: 'never',
+            parameters: [],
+            isNullable: false,
+            isGetAccessor: false,
+        };
+    }
+    // Handle Array
+    if (Array.isArray(targetType)) {
+        if (targetType.length === 0) {
+            throw new Error('@returns decorator array type must specify an element type, e.g., @returns(type => [String])');
+        }
+        const elementType = targetType[0];
+        const elementMetadata = analyzeReturnType(elementType);
+        return {
+            name: `${elementMetadata.name}[]`,
+            typeGroup: 'Array',
+            typeName: 'Array',
+            parameters: [elementMetadata],
+            isNullable: false,
+            isGetAccessor: false,
+        };
+    }
+    // Handle Class types (e.g., UUID, custom types)
+    if (typeof targetType === 'function') {
+        return {
+            name: targetType.name || 'Unknown',
+            typeGroup: 'Class',
+            typeName: targetType.name,
+            parameters: [],
+            isNullable: false,
+            isGetAccessor: false,
+            type: targetType,
+        };
+    }
+    // Default fallback
+    return {
+        name: 'unknown',
+        typeGroup: 'Other',
+        typeName: 'unknown',
+        parameters: [],
+        isNullable: false,
+        isGetAccessor: false,
+    };
+}
+/**
+ * Get the return type metadata for a method from decorator metadata.
+ *
+ * @param contextMetadata - The context.metadata from a class decorator
+ * @param methodName - The name of the method to get return type for
+ */
+function getReturnTypeMetadata(contextMetadata, methodName) {
+    if (!contextMetadata) {
+        return undefined;
+    }
+    const returnsMetadataList = contextMetadata[exports.RETURNS_METADATA_KEY];
+    if (!returnsMetadataList) {
+        return undefined;
+    }
+    const metadata = returnsMetadataList.find((m) => m.methodName === methodName);
+    if (!metadata) {
+        return undefined;
+    }
+    // Evaluate the type function and analyze the result
+    const typeResult = metadata.typeFunction();
+    // Return the actual type (not wrapped in Promise) - this is the GraphQL return type
+    return analyzeReturnType(typeResult);
+}
+/**
+ * @returns() decorator for explicit return type declaration on methods.
+ *
+ * Uses TC39 Stage 3 decorators to capture return type metadata that is used
+ * for GraphQL schema generation. The type specified should be the GraphQL
+ * return type (not wrapped in Promise).
+ *
+ * Usage:
+ *   @returns(type => UUID)
+ *   public static async handle(...): Promise<UUID> { ... }
+ *
+ *   @returns(type => String)
+ *   public static async handle(...): Promise<string> { ... }
+ *
+ *   @returns(type => [CartItem])
+ *   public static async handle(...): Promise<CartItem[]> { ... }
+ */
+function returns(typeFunction) {
+    return function returnsDecorator(_target, context) {
+        const methodName = context.name.toString();
+        // Store in context.metadata for later retrieval by class decorators
+        if (context.metadata) {
+            if (!context.metadata[exports.RETURNS_METADATA_KEY]) {
+                context.metadata[exports.RETURNS_METADATA_KEY] = [];
+            }
+            const returnsList = context.metadata[exports.RETURNS_METADATA_KEY];
+            // Remove any existing entry for this method (in case of decorator re-application)
+            const filteredList = returnsList.filter((m) => m.methodName !== methodName);
+            filteredList.push({
+                methodName,
+                typeFunction,
+            });
+            context.metadata[exports.RETURNS_METADATA_KEY] = filteredList;
+        }
+    };
+}

package/dist/event-processor.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MagekEventProcessor = void 0;
 const tslib_1 = require("tslib");
 const common_1 = require("@magek/common");
+const promises_1 = require("./utils/promises");
 const register_handler_1 = require("./register-handler");
 const global_error_dispatcher_1 = require("./global-error-dispatcher");
 const instrumentation_1 = require("./instrumentation");
@@ -33,7 +34,7 @@ let MagekEventProcessor = (() => {
                 if (!(entityName in config.topicToEvent)) {
                     eventEnvelopesProcessors.push(MagekEventProcessor.snapshotAndUpdateReadModels(config, entityName, entityID, eventStore, readModelStore));
                 }
-                await common_1.Promises.allSettledAndFulfilled(eventEnvelopesProcessors);
+                await promises_1.Promises.allSettledAndFulfilled(eventEnvelopesProcessors);
             };
         }
         static async filterDispatched(config, eventEnvelopes, eventStore) {
@@ -66,7 +67,7 @@ let MagekEventProcessor = (() => {
         static async dispatchEntityEventsToEventHandlers(entityEventEnvelopes, config) {
             const logger = (0, common_1.getLogger)(config, 'MagekEventDispatcher.dispatchEntityEventsToEventHandlers');
             try {
-                await common_1.Promises.allSettledAndFulfilled(entityEventEnvelopes.map(async (eventEnvelope) => {
+                await promises_1.Promises.allSettledAndFulfilled(entityEventEnvelopes.map(async (eventEnvelope) => {
                     let eventHandlers = config.eventHandlers[eventEnvelope.typeName] || [];
                     const globalEventHandler = config.eventHandlers[decorators_1.GLOBAL_EVENT_HANDLERS];
                     if (globalEventHandler && globalEventHandler.length > 0) {
@@ -79,13 +80,13 @@ let MagekEventProcessor = (() => {
                     const eventInstance = this.getEventInstance(config, eventEnvelope);
                     if (eventHandlers && eventHandlers.length > 0) {
                         try {
-                            await common_1.Promises.allSettledAndFulfilled(eventHandlers.map(async (eventHandler) => {
+                            await promises_1.Promises.allSettledAndFulfilled(eventHandlers.map(async (eventHandler) => {
                                 logger.debug('Calling "handle" method on event handler: ', eventHandler);
                                 await this.callEventHandler(eventHandler, eventInstance, eventEnvelope, config);
                             }));
                         }
                         catch (error) {
-                            if (error instanceof common_1.PromisesError) {
+                            if (error instanceof promises_1.PromisesError) {
                                 logger.error(`Failed to process handlers for event ${eventEnvelope.typeName}:`, error.failedReasons);
                             }
                             else {
@@ -96,7 +97,7 @@ let MagekEventProcessor = (() => {
                 }));
             }
             catch (error) {
-                if (error instanceof common_1.PromisesError) {
+                if (error instanceof promises_1.PromisesError) {
                     logger.error('Failed to process events:', error.failedReasons);
                 }
                 else {

package/dist/services/read-model-store.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReadModelStore = void 0;
 const common_1 = require("@magek/common");
+const promises_1 = require("../utils/promises");
 const global_error_dispatcher_1 = require("../global-error-dispatcher");
 const read_model_searcher_1 = require("./read-model-searcher");
 const read_model_schema_migrator_1 = require("../read-model-schema-migrator");
@@ -28,7 +29,7 @@ class ReadModelStore {
             const sequenceKey = this.sequenceKeyForProjection(entityInstance, projectionMetadata);
             return this.projectEntity(entityInstance, projectionMetadata, entityMetadata, entitySnapshotEnvelope, readModelName, deleteEvent, sequenceKey);
         });
-        await common_1.Promises.allSettledAndFulfilled(projectReadModelPromises);
+        await promises_1.Promises.allSettledAndFulfilled(projectReadModelPromises);
     }
     /**
      * Gets the read models for a given entity instance using the projection metadata
@@ -123,10 +124,10 @@ class ReadModelStore {
                 const newProjections = await this.projectionsForReadModels(entitySnapshotEnvelope, readModelName, sequenceKey, projectionMetadata, entityInstance, entityMetadata, deleteEvent, currentReadModel);
                 existingReadModelsProjections.push(...newProjections);
             }
-            return common_1.Promises.allSettledAndFulfilled(existingReadModelsProjections);
+            return promises_1.Promises.allSettledAndFulfilled(existingReadModelsProjections);
         }
         const newProjections = await this.projectionsForReadModels(entitySnapshotEnvelope, readModelName, sequenceKey, projectionMetadata, entityInstance, entityMetadata, deleteEvent);
-        return common_1.Promises.allSettledAndFulfilled(newProjections);
+        return promises_1.Promises.allSettledAndFulfilled(newProjections);
     }
     async projectionsForReadModels(entitySnapshotEnvelope, readModelName, sequenceKey, projectionMetadata, entityInstance, entityMetadata, deleteEvent, currentReadModel) {
         const projections = [];

package/dist/subscribers-notifier.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MagekSubscribersNotifier = void 0;
 const tslib_1 = require("tslib");
 const common_1 = require("@magek/common");
+const promises_1 = require("./utils/promises");
 const graphql = require("graphql");
 const graphql_generator_1 = require("./services/graphql/graphql-generator");
 const read_model_pub_sub_1 = require("./services/pub-sub/read-model-pub-sub");
@@ -32,7 +33,7 @@ let MagekSubscribersNotifier = (() => {
                 const subscriptions = await this.getSubscriptions(readModelEnvelopes);
                 logger.debug('Found the following subscriptions for those read models: ', subscriptions);
                 const pubSub = this.getPubSub(readModelEnvelopes);
-                await common_1.Promises.allSettledAndFulfilled(subscriptions.map(this.runSubscriptionAndNotify.bind(this, pubSub)));
+                await promises_1.Promises.allSettledAndFulfilled(subscriptions.map(this.runSubscriptionAndNotify.bind(this, pubSub)));
             }
             catch (e) {
                 logger.error(e);

package/dist/utils/promises.d.ts

@@ -0,0 +1,25 @@
+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/utils/promises.js

@@ -0,0 +1,43 @@
+"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magek/core",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Library for your Magek apps",
   "author": "Boosterin Labs SLU",
   "homepage": "https://magek.ai",
@@ -23,7 +23,7 @@
     "node": ">=22.0.0 <23.0.0"
   },
   "dependencies": {
-    "@magek/common": "^0.0.7",
+    "@magek/common": "^0.0.9",
     "fp-ts": "2.16.11",
     "graphql-scalars": "1.25.0",
     "inflected": "2.1.0",
@@ -35,7 +35,7 @@
     "fast-check": "4.5.3"
   },
   "devDependencies": {
-    "@magek/eslint-config": "^0.0.7",
+    "@magek/eslint-config": "^0.0.9",
     "@types/chai": "5.2.3",
     "@types/chai-as-promised": "8.0.2",
     "@types/inflected": "2.1.3",