@opra/core 1.26.3 → 1.27.0

package/README.md

@@ -1,3 +1,26 @@
 # @opra/core
 
-OPRA schema package.
+[![NPM Version][npm-image]][npm-url]
+[![NPM Downloads][downloads-image]][downloads-url]
+[![CI Tests][ci-test-image]][ci-test-url]
+[![Test Coverage][coveralls-image]][coveralls-url]
+
+
+## Support
+You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.
+
+## Node Compatibility
+- node >= 20.x
+
+
+## License
+Available under [MIT](LICENSE) license.
+
+[npm-image]: https://img.shields.io/npm/v/@opra/core
+[npm-url]: https://npmjs.org/package/@opra/core
+[downloads-image]: https://img.shields.io/npm/dm/@opra/core.svg
+[downloads-url]: https://npmjs.org/package/@opra/core
+[ci-test-image]: https://github.com/panates/opra/actions/workflows/test.yml/badge.svg
+[ci-test-url]: https://github.com/panates/opra/actions/workflows/test.yml
+[coveralls-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=main
+[coveralls-url]: https://coveralls.io/github/panates/opra?branch=main

package/asset-cache.d.ts

@@ -1,6 +1,31 @@
+/**
+ * AssetCache is a utility class for caching assets associated with objects.
+ * It uses a WeakMap to store assets, ensuring that they are garbage collected
+ * when the objects themselves are no longer referenced.
+ */
 export declare class AssetCache {
     protected _items: WeakMap<any, Record<string, any>>;
+    /**
+     * Retrieves an asset from the cache for a given object and asset name.
+     *
+     * @param obj - The object associated with the asset.
+     * @param name - The name of the asset.
+     * @returns The cached asset, or undefined if not found.
+     */
     get<T>(obj: any, name: string): T | undefined;
+    /**
+     * Stores an asset in the cache for a given object and asset name.
+     *
+     * @param obj - The object to associate with the asset.
+     * @param name - The name of the asset.
+     * @param asset - The asset to be cached.
+     */
     set(obj: any, name: string, asset: any): void;
+    /**
+     * Removes an asset from the cache for a given object and asset name.
+     *
+     * @param obj - The object associated with the asset.
+     * @param name - The name of the asset to be removed.
+     */
     delete(obj: any, name: string): void;
 }

package/asset-cache.js

@@ -1,9 +1,28 @@
+/**
+ * AssetCache is a utility class for caching assets associated with objects.
+ * It uses a WeakMap to store assets, ensuring that they are garbage collected
+ * when the objects themselves are no longer referenced.
+ */
 export class AssetCache {
     _items = new WeakMap();
+    /**
+     * Retrieves an asset from the cache for a given object and asset name.
+     *
+     * @param obj - The object associated with the asset.
+     * @param name - The name of the asset.
+     * @returns The cached asset, or undefined if not found.
+     */
     get(obj, name) {
         const cache = this._items.get(obj);
         return cache && cache[name];
     }
+    /**
+     * Stores an asset in the cache for a given object and asset name.
+     *
+     * @param obj - The object to associate with the asset.
+     * @param name - The name of the asset.
+     * @param asset - The asset to be cached.
+     */
     set(obj, name, asset) {
         let cache = this._items.get(obj);
         if (!cache) {
@@ -12,6 +31,12 @@ export class AssetCache {
         }
         cache[name] = asset;
     }
+    /**
+     * Removes an asset from the cache for a given object and asset name.
+     *
+     * @param obj - The object associated with the asset.
+     * @param name - The name of the asset to be removed.
+     */
     delete(obj, name) {
         const cache = this._items.get(obj);
         if (!cache)

package/execution-context.d.ts

@@ -2,24 +2,42 @@ import { DocumentNode, OpraSchema } from '@opra/common';
 import { AsyncEventEmitter } from 'node-events-async';
 import type { PlatformAdapter } from './platform-adapter.js';
 /**
- * @class ExecutionContext
+ * ExecutionContext provides a context for executing operations within an adapter.
+ * It carries information about the document node, adapter, transport, and platform.
  */
 export declare class ExecutionContext extends AsyncEventEmitter {
+    /** The document node associated with this context */
     readonly __docNode: DocumentNode;
+    /** The platform adapter that created this context */
     readonly __adapter: PlatformAdapter;
+    /** The transport protocol being used (e.g., 'http', 'socketio') */
     readonly transport?: OpraSchema.Transport;
+    /** The platform name (e.g., 'express', 'koa') */
     readonly platform: string;
+    /** A collection of errors encountered during execution */
     errors: Error[];
+    /**
+     * Creates a new ExecutionContext instance.
+     *
+     * @param init - The initialization parameters for the context.
+     */
     constructor(init: ExecutionContext.Initiator);
 }
 /**
- * @namespace ExecutionContext
+ * Namespace for {@link ExecutionContext} related types and interfaces.
  */
 export declare namespace ExecutionContext {
+    /**
+     * Initialization parameters for creating an {@link ExecutionContext}.
+     */
     interface Initiator {
+        /** The platform adapter */
         __adapter: PlatformAdapter;
+        /** The document node */
         __docNode: DocumentNode;
+        /** The transport protocol */
         transport?: OpraSchema.Transport;
+        /** The platform name */
         platform?: string;
     }
 }

package/execution-context.js

@@ -1,13 +1,24 @@
 import { AsyncEventEmitter } from 'node-events-async';
 /**
- * @class ExecutionContext
+ * ExecutionContext provides a context for executing operations within an adapter.
+ * It carries information about the document node, adapter, transport, and platform.
  */
 export class ExecutionContext extends AsyncEventEmitter {
+    /** The document node associated with this context */
     __docNode;
+    /** The platform adapter that created this context */
     __adapter;
+    /** The transport protocol being used (e.g., 'http', 'socketio') */
     transport;
+    /** The platform name (e.g., 'express', 'koa') */
     platform = '';
+    /** A collection of errors encountered during execution */
     errors = [];
+    /**
+     * Creates a new ExecutionContext instance.
+     *
+     * @param init - The initialization parameters for the context.
+     */
     constructor(init) {
         super();
         this.__adapter = init.__adapter;

package/interfaces/logger.interface.d.ts

@@ -1,9 +1,56 @@
+/**
+ * Interface for logging services used within the OPRA framework.
+ * This interface defines standard logging methods that can be implemented
+ * by various logging providers (e.g., Winston, Pino, or a simple console logger).
+ */
 export interface ILogger {
+    /**
+     * Logs an error message.
+     *
+     * @param message - The error message or object.
+     * @param optionalParams - Additional parameters for formatting the message.
+     */
     error(message: any, ...optionalParams: any[]): void;
+    /**
+     * Logs a general log message.
+     *
+     * @param message - The message or object.
+     * @param optionalParams - Additional parameters for formatting the message.
+     */
     log?(message: any, ...optionalParams: any[]): void;
+    /**
+     * Logs an informational message.
+     *
+     * @param message - The message or object.
+     * @param optionalParams - Additional parameters for formatting the message.
+     */
     info?(message: any, ...optionalParams: any[]): void;
+    /**
+     * Logs a warning message.
+     *
+     * @param message - The message or object.
+     * @param optionalParams - Additional parameters for formatting the message.
+     */
     warn?(message: any, ...optionalParams: any[]): void;
+    /**
+     * Logs a fatal error message.
+     *
+     * @param message - The message or object.
+     * @param optionalParams - Additional parameters for formatting the message.
+     */
     fatal?(message: any, ...optionalParams: any[]): void;
+    /**
+     * Logs a debug message.
+     *
+     * @param message - The message or object.
+     * @param optionalParams - Additional parameters for formatting the message.
+     */
     debug?(message: any, ...optionalParams: any[]): void;
+    /**
+     * Logs a verbose message.
+     *
+     * @param message - The message or object.
+     * @param optionalParams - Additional parameters for formatting the message.
+     */
     verbose?(message: any, ...optionalParams: any[]): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/core",
-  "version": "1.26.3",
+  "version": "1.27.0",
   "description": "Opra schema package",
   "author": "Panates",
   "license": "MIT",
@@ -10,7 +10,7 @@
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@opra/common": "^1.26.3"
+    "@opra/common": "^1.27.0"
   },
   "type": "module",
   "module": "./index.js",

package/platform-adapter.d.ts

@@ -6,26 +6,57 @@ import { kAssetCache } from './constants.js';
 import { ExecutionContext } from './execution-context.js';
 import { ILogger } from './interfaces/logger.interface.js';
 /**
- * @class PlatformAdapter
+ * Base class for all platform adapters in the OPRA framework.
+ * A platform adapter bridge between a specific platform (like Express, Socket.io, etc.)
+ * and the OPRA application logic.
+ *
+ * @typeParam T - The event map type for the adapter.
  */
 export declare abstract class PlatformAdapter<T extends EventMap<T> = never> extends AsyncEventEmitter<T> {
     protected [kAssetCache]: AssetCache;
     protected _document: ApiDocument;
+    /** The transport protocol supported by this adapter */
     abstract readonly transform: OpraSchema.Transport;
+    /** The platform name of this adapter */
     abstract readonly platform: string;
+    /** Internationalization service instance */
     i18n: I18n;
+    /** Logger instance for the adapter */
     logger?: ILogger;
+    /**
+     * Initializes the platform adapter.
+     *
+     * @param options - Configuration options for the adapter.
+     */
     protected constructor(options?: PlatformAdapter.Options);
+    /**
+     * Returns the API document associated with this adapter.
+     */
     get document(): ApiDocument;
+    /**
+     * Closes the adapter and releases any resources.
+     *
+     * @returns A promise that resolves when the adapter is closed.
+     */
     abstract close(): Promise<void>;
+    /**
+     * Creates a root execution context for the adapter.
+     *
+     * @returns A new {@link ExecutionContext} instance.
+     */
     createRootContext(): ExecutionContext;
 }
 /**
- * @namespace PlatformAdapter
+ * Namespace for {@link PlatformAdapter} related types and interfaces.
  */
 export declare namespace PlatformAdapter {
+    /**
+     * Configuration options for {@link PlatformAdapter}.
+     */
     interface Options {
+        /** The internationalization instance to use */
         i18n?: I18n;
+        /** The logger instance to use */
         logger?: ILogger;
     }
 }

package/platform-adapter.js

@@ -5,21 +5,40 @@ import { AssetCache } from './asset-cache.js';
 import { kAssetCache } from './constants.js';
 import { ExecutionContext } from './execution-context.js';
 /**
- * @class PlatformAdapter
+ * Base class for all platform adapters in the OPRA framework.
+ * A platform adapter bridge between a specific platform (like Express, Socket.io, etc.)
+ * and the OPRA application logic.
+ *
+ * @typeParam T - The event map type for the adapter.
  */
 export class PlatformAdapter extends AsyncEventEmitter {
     [kAssetCache];
+    /** Internationalization service instance */
     i18n;
+    /** Logger instance for the adapter */
     logger;
+    /**
+     * Initializes the platform adapter.
+     *
+     * @param options - Configuration options for the adapter.
+     */
     constructor(options) {
         super();
         this[kAssetCache] = new AssetCache();
         this.i18n = options?.i18n || I18n.defaultInstance;
         this.logger = options?.logger;
     }
+    /**
+     * Returns the API document associated with this adapter.
+     */
     get document() {
         return this._document;
     }
+    /**
+     * Creates a root execution context for the adapter.
+     *
+     * @returns A new {@link ExecutionContext} instance.
+     */
     createRootContext() {
         return new ExecutionContext({
             __adapter: this,

package/service-base.d.ts

@@ -1,15 +1,53 @@
 import type { Nullish } from 'ts-gems';
 import type { ExecutionContext } from './execution-context.js';
+/**
+ * Base class for services in the OPRA framework.
+ * Provides access to the {@link ExecutionContext} and allows creating new
+ * service instances with modified context or properties.
+ */
 export declare abstract class ServiceBase {
     protected _context?: ExecutionContext;
+    /**
+     * Initializes the service with optional configuration.
+     *
+     * @param options - Configuration options for the service.
+     */
     constructor(options?: ServiceBase.Options);
+    /**
+     * Returns the execution context associated with this service.
+     *
+     * @throws {@link Error} if no context is assigned to the service.
+     * @returns The execution context.
+     */
     get context(): ExecutionContext;
+    /**
+     * Creates a new instance of the service with a modified context or properties.
+     *
+     * @param context - The execution context or another service to inherit the context from.
+     * @param overwriteProperties - Optional properties to overwrite in the new service instance.
+     * @param overwriteContext - Optional context properties to overwrite in the new context.
+     * @returns A new service instance with the specified modifications.
+     */
     for<C extends ExecutionContext, P extends Partial<this>>(context: C | ServiceBase, overwriteProperties?: Nullish<P>, overwriteContext?: Partial<C>): this & Required<P>;
+    /**
+     * Asserts that a context is assigned to the service.
+     *
+     * @throws {@link Error} if no context is assigned.
+     * @protected
+     */
     protected _assertContext(): void;
 }
+/**
+ * Namespace for {@link ServiceBase} related constants and interfaces.
+ */
 export declare namespace ServiceBase {
+    /** Symbol used for extending service instances. */
     const extendSymbol: unique symbol;
+    /**
+     * Configuration options for {@link ServiceBase}.
+     */
     interface Options {
+        /** The execution context to be associated with the service. */
         context?: ExecutionContext;
     }
 }

package/service-base.js

@@ -1,20 +1,44 @@
+/**
+ * Base class for services in the OPRA framework.
+ * Provides access to the {@link ExecutionContext} and allows creating new
+ * service instances with modified context or properties.
+ */
 export class ServiceBase {
+    /**
+     * Initializes the service with optional configuration.
+     *
+     * @param options - Configuration options for the service.
+     */
     constructor(options) {
         this._context = options?.context;
     }
+    /**
+     * Returns the execution context associated with this service.
+     *
+     * @throws {@link Error} if no context is assigned to the service.
+     * @returns The execution context.
+     */
     get context() {
         this._assertContext();
         return this._context;
     }
+    /**
+     * Creates a new instance of the service with a modified context or properties.
+     *
+     * @param context - The execution context or another service to inherit the context from.
+     * @param overwriteProperties - Optional properties to overwrite in the new service instance.
+     * @param overwriteContext - Optional context properties to overwrite in the new context.
+     * @returns A new service instance with the specified modifications.
+     */
     for(context, overwriteProperties, overwriteContext) {
         if (context instanceof ServiceBase)
             context = context.context;
-        /** Create a new context instance */
+        /* Create a new context instance */
         const ctx = {};
         Object.setPrototypeOf(ctx, context);
         if (overwriteContext)
             Object.assign(ctx, overwriteContext);
-        /** Create a new service instance */
+        /* Create a new service instance */
         const instance = { _context: ctx };
         Object.setPrototypeOf(instance, this);
         if (overwriteProperties)
@@ -23,11 +47,21 @@ export class ServiceBase {
             this[ServiceBase.extendSymbol](instance);
         return instance;
     }
+    /**
+     * Asserts that a context is assigned to the service.
+     *
+     * @throws {@link Error} if no context is assigned.
+     * @protected
+     */
     _assertContext() {
         if (!this._context)
             throw new Error(`No context assigned for ${Object.getPrototypeOf(this).constructor.name}`);
     }
 }
+/**
+ * Namespace for {@link ServiceBase} related constants and interfaces.
+ */
 (function (ServiceBase) {
+    /** Symbol used for extending service instances. */
     ServiceBase.extendSymbol = Symbol('extend');
 })(ServiceBase || (ServiceBase = {}));