@tramvai/core 2.7.1 → 2.20.0

package/README.md

@@ -83,31 +83,54 @@ class ModulePubSub {
 }
 ```
 
-### createAction
+### declareAction
 
-`createAction` - Method for creating asynchronous actions. It is used both for building chains of sagas and for performing global actions when building a response to a client
+`declareAction` - Method for creating asynchronous actions. It is used both for building chains of sagas and for performing global actions when building a response to a client
 
 [More about actions](concepts/action.md)
 
-#### createAction({ name, fn, deps, conditions })
+#### declareAction({ name, fn, deps, conditions })
 
 - `name` - The name of the action, a unique identifier is expected
-- `fn(context, payload, deps)` - Implementation of the action, this function will be called when the action is used, maybe `async`
-  - `context` - [ConsumerContext](references/tokens/common.md#context-tokens-list)
-  - `payload` - data passed to action
-  - `deps` - provider instances from `deps`
+- `fn(...params)` - Implementation of the action, this function will be called when the action is used, maybe `async`
+  - `this` - action execution context that contains some helper functions and resolved deps
+  - `params` - data passed to action
 - `deps` - List of providers that are needed for the action to work
 - `conditions` - List of restrictions for the execution of the action
+- `conditionsFailResult` - [see](#conditionsfailresult)
+
+#### Action Execution Context
+
+Action execution context that contains some helper functions and resolved deps
+
+Context has next fields:
+- `deps` - resolved deps that were specified when declaring action
+- `executeAction` - allows to execute another actions inside current one
+- `getState` - quick access to `STORE_TOKEN.getState`
+- `dispatch` - quick access to `STORE_TOKEN.dispatch`
+- `abortSignal` - instance of signal related to the current execution tree
+- `abortController` - instance of `AbortController` created exclusively for the current action execution
+
+#### conditionsFailResult
+
+Specifies the output of the action in case its `conditions` was not met during execution.
+
+> If `conditions` are not met for action, action's `fn` won't be executed in any way
+
+Possible values for the `conditionsFailResult`:
+- `empty` - (default) execution will be resolved with `undefined` as a result
+- `error` - execution will be rejected with [ConditionFailError](references/libs/errors.md#conditionfailerror)
+
 
 #### Usage example
 
 ```tsx
-import { createAction } from '@tramvai/core';
+import { declareAction } from '@tramvai/core';
 
-createAction({
+declareAction({
   name: 'action log error',
-  fn: (context, payload, deps) => {
-    deps.logger.error('ERROR');
+  fn(payload) {
+    this.deps.logger.error('ERROR');
   },
   deps: {
     logger: 'logger',
@@ -118,6 +141,33 @@ createAction({
 });
 ```
 
+abort execution:
+```ts
+const innerAction = declareAction(/** ... */);
+
+const action = declareAction({
+  name: 'root',
+  async fn() {
+    setTimeout(() => {
+      this.abortController.abort()
+    }, 4000);
+
+    const { payload } = await this.deps.httpClient.request({
+      url: 'https://www.domain.com/api/endpoint',
+      // pass signal to the request
+      signal: this.abortSignal,
+    });
+
+    // if innerAction1 will end after abortController.abort was called
+    // then calling innerAction2 will throw an instance of ExecutionAbortError
+    await this.executeAction(innerAction, payload);
+  },
+  deps: {
+    httpClient: HTTP_CLIENT,
+  },
+});
+```
+
 ### createBundle
 
 `createBundle(options: BundleOptions)` - method to create a bundle.

package/lib/actions/createActions.d.ts

@@ -1,2 +1,5 @@
 import type { ActionParameters, Action } from '@tramvai/tokens-core';
+/**
+ * @deprecated: use `declareAction`
+ */
 export declare function createAction<Result = any, Payload = any, Deps = any>(action: ActionParameters<Payload, Result, Deps>): Action<Payload, Result, Deps>;

package/lib/actions/declareAction.d.ts

@@ -0,0 +1,3 @@
+import type { TramvaiAction, TramvaiActionDefinition } from '@tramvai/types-actions-state-context';
+export declare function declareAction<Params extends any[], Result, Deps = {}>(action: TramvaiActionDefinition<Params, Result, Deps>): TramvaiAction<Params, Result, Deps>;
+export declare function isTramvaiAction<Params extends any[], Result, Deps>(action: any): action is TramvaiAction<Params, Result, Deps>;

package/lib/actions/declareAction.test-types.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 export { createApp, App } from './createApp';
 export { createBundle } from './bundles/createBundle';
 export { createAction } from './actions/createActions';
+export * from './actions/declareAction';
 export { Module, deprecatedModule as module, MODULE_PARAMETERS } from './modules/module';
 export { getModuleParameters } from './modules/getModuleParameters';
 export { walkOfModules } from './modules/walkOfModules';

package/lib/index.es.js

@@ -225,6 +225,9 @@ function createBundle(options) {
     return mergeOptions(presets, options);
 }
 
+/**
+ * @deprecated: use `declareAction`
+ */
 function createAction(action) {
     const result = Object.assign(action.fn, {
         [ACTION_PARAMETERS]: action,
@@ -236,4 +239,14 @@ function createAction(action) {
     return result;
 }
 
-export { App, MODULE_PARAMETERS, Module, createAction, createApp, createBundle, getModuleParameters, isExtendedModule, deprecatedModule as module, walkOfModules };
+function declareAction(action) {
+    return {
+        ...action,
+        tramvaiActionVersion: 2,
+    };
+}
+function isTramvaiAction(action) {
+    return 'tramvaiActionVersion' in action && action.tramvaiActionVersion === 2;
+}
+
+export { App, MODULE_PARAMETERS, Module, createAction, createApp, createBundle, declareAction, getModuleParameters, isExtendedModule, isTramvaiAction, deprecatedModule as module, walkOfModules };

package/lib/index.js

@@ -233,6 +233,9 @@ function createBundle(options) {
     return mergeOptions(presets, options);
 }
 
+/**
+ * @deprecated: use `declareAction`
+ */
 function createAction(action) {
     const result = Object.assign(action.fn, {
         [tokensCore.ACTION_PARAMETERS]: action,
@@ -244,6 +247,16 @@ function createAction(action) {
     return result;
 }
 
+function declareAction(action) {
+    return {
+        ...action,
+        tramvaiActionVersion: 2,
+    };
+}
+function isTramvaiAction(action) {
+    return 'tramvaiActionVersion' in action && action.tramvaiActionVersion === 2;
+}
+
 Object.defineProperty(exports, 'DI_TOKEN', {
     enumerable: true,
     get: function () { return dippy.DI_TOKEN; }
@@ -274,8 +287,10 @@ exports.Module = Module;
 exports.createAction = createAction;
 exports.createApp = createApp;
 exports.createBundle = createBundle;
+exports.declareAction = declareAction;
 exports.getModuleParameters = getModuleParameters;
 exports.isExtendedModule = isExtendedModule;
+exports.isTramvaiAction = isTramvaiAction;
 exports.module = deprecatedModule;
 exports.walkOfModules = walkOfModules;
 Object.keys(tokensCore).forEach(function (k) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tramvai/core",
-  "version": "2.7.1",
+  "version": "2.20.0",
   "description": "",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -20,10 +20,10 @@
   },
   "dependencies": {
     "@tinkoff/utils": "^2.1.2",
-    "@tramvai/tokens-common": "2.7.1",
-    "@tramvai/tokens-core": "2.7.1",
-    "@tramvai/types-actions-state-context": "2.7.1",
-    "@tinkoff/dippy": "0.7.44",
+    "@tramvai/tokens-common": "2.20.0",
+    "@tramvai/tokens-core": "2.20.0",
+    "@tramvai/types-actions-state-context": "2.20.0",
+    "@tinkoff/dippy": "0.8.2",
     "tslib": "^2.0.3"
   },
   "peerDependencies": {