@opra/core 1.28.4 → 1.29.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Panates
+Copyright (c) 2020-present Panates®
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,47 @@
+<div align="center">
+
+<a href="https://oprajs.com">
+  <img src="https://oprajs.com/img/opra-header-block.webp" width="880" alt="OPRA — Open Platform for Rich APIs" />
+</a>
+
 # @opra/core
 
+Runtime engine of the OPRA framework — request lifecycle, validation, and routing
+
 [![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]
 
+[🌐 Documentation](https://oprajs.com) · [🚀 Getting Started](https://oprajs.com/docs/introduction) · [📦 Packages](https://github.com/panates/opra#packages) · [💬 Issues](https://github.com/panates/opra/issues)
+
+</div>
+
+---
+
+Core runtime package of the [OPRA](https://oprajs.com) framework. Provides the execution engine, platform adapter base classes, service patterns, and infrastructure utilities that all OPRA adapters and services depend on.
 
-## Support
-You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.
+## Features
+
+- **Platform Adapter Base** — Abstract foundation for HTTP, Socket.IO, Kafka, RabbitMQ, and other transport adapters
+- **Execution Context** — Request-scoped context carrying adapter, document, transport, and platform references
+- **Service Pattern** — `ServiceBase` with context propagation and immutable `.for()` cloning
+- **i18n Support** — Built-in internationalization with lazy-loading of resource bundles and localized error messages
+- **Asset Cache** — WeakMap-based cache for automatic memory-safe asset lifecycle management
+- **Event-Driven** — `AsyncEventEmitter`-based lifecycle hooks on both adapters and execution contexts
+
+## Installation
+
+```bash
+npm install @opra/core
+```
 
 ## Node Compatibility
-- node >= 20.x
 
+- node >= 20.x
 
 ## License
+
 Available under [MIT](LICENSE) license.
 
 [npm-image]: https://img.shields.io/npm/v/@opra/core
@@ -22,5 +50,5 @@ Available under [MIT](LICENSE) license.
 [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-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=dev
 [coveralls-url]: https://coveralls.io/github/panates/opra?branch=main

package/execution-bundle.d.ts

@@ -0,0 +1,44 @@
+import { OpraException, OpraSchema } from '@opra/common';
+import { AsyncEventEmitter } from 'node-events-async';
+import type { ExecutionContext } from './execution-context.js';
+import type { PlatformAdapter } from './platform-adapter.js';
+/**
+ * ExecutionBundle provides a context for executing multiple operations.
+ */
+export declare class ExecutionBundle extends AsyncEventEmitter {
+    /** 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 ExecutionContext created during execution */
+    contexts: ExecutionContext[];
+    /** Whether a transaction will be used in this bundle context */
+    readonly transaction?: boolean;
+    success?: boolean;
+    finished?: boolean;
+    error?: OpraException;
+    /**
+     * Creates a new ExecutionContext instance.
+     *
+     * @param init - The initialization parameters for the context.
+     */
+    constructor(init: ExecutionBundle.Initiator);
+}
+/**
+ * Namespace for {@link ExecutionBundle} related types and interfaces.
+ */
+export declare namespace ExecutionBundle {
+    /**
+     * Initialization parameters for creating an {@link ExecutionBundle}.
+     */
+    interface Initiator {
+        /** The platform adapter */
+        __adapter: PlatformAdapter;
+        /** The transport protocol */
+        transport?: OpraSchema.Transport;
+        /** The platform name */
+        platform?: string;
+    }
+}

package/execution-bundle.js

@@ -0,0 +1,31 @@
+import { OpraException, OpraSchema } from '@opra/common';
+import { AsyncEventEmitter } from 'node-events-async';
+/**
+ * ExecutionBundle provides a context for executing multiple operations.
+ */
+export class ExecutionBundle extends AsyncEventEmitter {
+    /** 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 ExecutionContext created during execution */
+    contexts = [];
+    /** Whether a transaction will be used in this bundle context */
+    transaction;
+    success;
+    finished;
+    error;
+    /**
+     * Creates a new ExecutionContext instance.
+     *
+     * @param init - The initialization parameters for the context.
+     */
+    constructor(init) {
+        super();
+        this.__adapter = init.__adapter;
+        this.transport = init.transport;
+        this.platform = init.platform || '';
+    }
+}

package/execution-context.d.ts

@@ -1,21 +1,26 @@
 import { DocumentNode, OpraSchema } from '@opra/common';
-import { AsyncEventEmitter } from 'node-events-async';
+import { AsyncEventEmitter, type EventMap } from 'node-events-async';
+import type { ExecutionBundle } from './execution-bundle.js';
 import type { PlatformAdapter } from './platform-adapter.js';
 /**
  * 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;
+export declare class ExecutionContext<T extends EventMap<T> = never> extends AsyncEventEmitter<T> {
     /** The platform adapter that created this context */
     readonly __adapter: PlatformAdapter;
+    /** The document node associated with this context */
+    readonly __docNode: DocumentNode;
+    /** The execution bundle associated with this context */
+    readonly bundle?: ExecutionBundle;
     /** 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[];
+    success?: boolean;
+    finished?: boolean;
     /**
      * Creates a new ExecutionContext instance.
      *
@@ -35,6 +40,8 @@ export declare namespace ExecutionContext {
         __adapter: PlatformAdapter;
         /** The document node */
         __docNode: DocumentNode;
+        /** The execution bundle */
+        bundle?: ExecutionBundle;
         /** The transport protocol */
         transport?: OpraSchema.Transport;
         /** The platform name */

package/execution-context.js

@@ -5,16 +5,20 @@ import { AsyncEventEmitter } from 'node-events-async';
  * 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 document node associated with this context */
+    __docNode;
+    /** The execution bundle associated with this context */
+    bundle;
     /** 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 = [];
+    success;
+    finished;
     /**
      * Creates a new ExecutionContext instance.
      *
@@ -24,6 +28,7 @@ export class ExecutionContext extends AsyncEventEmitter {
         super();
         this.__adapter = init.__adapter;
         this.__docNode = init.__docNode;
+        this.bundle = init.bundle;
         this.transport = init.transport;
         this.platform = init.platform || '';
     }

package/index.d.ts

@@ -2,6 +2,7 @@ import 'reflect-metadata';
 import './augmentation/18n.augmentation.js';
 export * from './asset-cache.js';
 export * from './constants.js';
+export * from './execution-bundle.js';
 export * from './execution-context.js';
 export * from './interfaces/logger.interface.js';
 export * from './platform-adapter.js';

package/index.js

@@ -2,6 +2,7 @@ import 'reflect-metadata';
 import './augmentation/18n.augmentation.js';
 export * from './asset-cache.js';
 export * from './constants.js';
+export * from './execution-bundle.js';
 export * from './execution-context.js';
 export * from './interfaces/logger.interface.js';
 export * from './platform-adapter.js';

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@opra/core",
-  "version": "1.28.4",
+  "version": "1.29.0",
   "description": "Opra schema package",
   "author": "Panates",
   "license": "MIT",
+  "homepage": "https://www.oprajs.com",
   "dependencies": {
     "node-events-async": "^1.5.2",
     "reflect-metadata": "^0.2.2",
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@opra/common": "^1.28.4"
+    "@opra/common": "^1.29.0"
   },
   "type": "module",
   "module": "./index.js",