Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@travetto/base
Advanced tools
@travetto/base - npm Package Compare versions
Comparing version 3.0.2 to 3.0.3
| { | ||
| "name": "@travetto/base", | ||
| "version": "3.0.2", | ||
| "version": "3.0.3", | ||
| "description": "Environment config and common utilities for travetto applications.", | ||
@@ -29,3 +29,3 @@ "keywords": [ | ||
| "dependencies": { | ||
| "@travetto/manifest": "^3.0.2", | ||
| "@travetto/manifest": "^3.0.3", | ||
| "@types/source-map-support": "^0.5.6", | ||
@@ -35,3 +35,3 @@ "source-map-support": "^0.5.21" | ||
| "peerDependencies": { | ||
| "@travetto/transformer": "^3.0.2" | ||
| "@travetto/transformer": "^3.0.3" | ||
| }, | ||
@@ -38,0 +38,0 @@ "peerDependenciesMeta": { |
| <!-- This file was generated by @travetto/doc and should not be modified directly --> | ||
| <!-- Please modify https://github.com/travetto/travetto/tree/main/module/base/DOC.ts and execute "npx trv doc" to rebuild --> | ||
| <!-- Please modify https://github.com/travetto/travetto/tree/main/module/base/DOC.tsx and execute "npx trv doc" to rebuild --> | ||
| # Base | ||
| ## Environment config and common utilities for travetto applications. | ||
@@ -16,4 +17,2 @@ | ||
| Base is the foundation of all [Travetto](https://travetto.dev) applications. It is intended to be a minimal application set, as well as support for commonly shared functionality. It has support for the following key areas: | ||
| * Environment Support | ||
@@ -34,3 +33,2 @@ * Shared Global Environment State | ||
| The functionality we support for testing and retrieving environment information: | ||
| * `isTrue(key: string): boolean;` - Test whether or not an environment flag is set and is true | ||
@@ -72,4 +70,2 @@ * `isFalse(key: string): boolean;` - Test whether or not an environment flag is set and is false | ||
| The source for each field is: | ||
| * `envName` - This is derived from `process.env.TRV_ENV` with a fallback of `process.NODE_ENV` | ||
@@ -82,3 +78,2 @@ * `prod` - This is true if `envName` is a prod value | ||
| * `nodeVersion` - This is derived from `process.version`, and is used primarily for logging purposes | ||
| In addition to reading these values, there is a defined method for setting/updating these values: | ||
@@ -117,6 +112,5 @@ | ||
| As you can see this method exists to update/change the `process.env` values so that the usage of [GlobalEnv](https://github.com/travetto/travetto/tree/main/module/base/src/global-env.ts#L10) reflects these changes. This is primarily used in testing, or custom environment setups (e.g. CLI invocations for specific applications). | ||
| As you can see this method exists to update/change the `process.env` values so that the usage of [GlobalEnv](https://github.com/travetto/travetto/tree/main/module/base/src/global-env.ts#L10) reflects these changes. This is primarily used in testing, or custom environment setups (e.g. CLI invocations for specific applications). | ||
| ## Resource Access | ||
| The primary access patterns for resources, is to directly request a file, and to resolve that file either via file-system look up or leveraging the [Manifest](https://github.com/travetto/travetto/tree/main/module/manifest#readme "Support for project indexing, manifesting, along with file watching")'s data for what resources were found at manifesting time. | ||
@@ -149,3 +143,3 @@ | ||
| The [ResourceProvider](https://github.com/travetto/travetto/tree/main/module/base/src/resource.ts#L21) allows for accessing information about the resources, and subsequently reading the file as text/binary or to access the resource as a `Readable` stream. If a file is not found, it will throw an [AppError](https://github.com/travetto/travetto/tree/main/module/base/src/error.ts#L13) with a category of 'notfound'. This contract is fairly simple to fill out, and the predominant implementation is [FileResourceProvider](https://github.com/travetto/travetto/tree/main/module/base/src/resource.ts#L46). This [ResourceProvider](https://github.com/travetto/travetto/tree/main/module/base/src/resource.ts#L21) will utilize the [GlobalEnv](https://github.com/travetto/travetto/tree/main/module/base/src/global-env.ts#L10)'s `resourcePaths` information on where to attempt to find a requested resource. | ||
| The [ResourceProvider](https://github.com/travetto/travetto/tree/main/module/base/src/resource.ts#L21) allows for accessing information about the resources, and subsequently reading the file as text/binary or to access the resource as a `Readable` stream. If a file is not found, it will throw an [AppError](https://github.com/travetto/travetto/tree/main/module/base/src/error.ts#L13) with a category of 'notfound'. This contract is fairly simple to fill out, and the predominant implementation is [FileResourceProvider](https://github.com/travetto/travetto/tree/main/module/base/src/resource.ts#L46). This [ResourceProvider](https://github.com/travetto/travetto/tree/main/module/base/src/resource.ts#L21) will utilize the [GlobalEnv](https://github.com/travetto/travetto/tree/main/module/base/src/global-env.ts#L10)'s `resourcePaths` information on where to attempt to find a requested resource. | ||
@@ -158,7 +152,5 @@ ### Scanning for Resources | ||
| ## Standard Error Support | ||
| While the framework is 100 % compatible with standard `Error` instances, there are cases in which additional functionality is desired. Within the framework we use [AppError](https://github.com/travetto/travetto/tree/main/module/base/src/error.ts#L13) (or its derivatives) to represent framework errors. This class is available for use in your own projects. Some of the additional benefits of using this class is enhanced error reporting, as well as better integration with other modules (e.g. the [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") module and HTTP status codes). | ||
| While the framework is 100 % compatible with standard `Error` instances, there are cases in which additional functionality is desired. Within the framework we use [AppError](https://github.com/travetto/travetto/tree/main/module/base/src/error.ts#L13) (or its derivatives) to represent framework errors. This class is available for use in your own projects. Some of the additional benefits of using this class is enhanced error reporting, as well as better integration with other modules (e.g. the [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") module and HTTP status codes). | ||
| The [AppError](https://github.com/travetto/travetto/tree/main/module/base/src/error.ts#L13) takes in a message, and an optional payload and / or error classification. The currently supported error classifications are: | ||
| * `general` - General purpose errors | ||
@@ -174,7 +166,5 @@ * `system` - Synonym for `general` | ||
| ## Console Management | ||
| This module provides logging functionality, built upon [console](https://nodejs.org/api/console.html) operations. | ||
| The supported operations are: | ||
| * `console.error` which logs at the `ERROR` level | ||
@@ -189,5 +179,4 @@ * `console.warn` which logs at the `WARN` level | ||
| ## How Logging is Instrumented | ||
| All of the logging instrumentation occurs at transpilation time. All `console.*` methods are replaced with a call to a globally defined variable that delegates to the [ConsoleManager](https://github.com/travetto/travetto/tree/main/module/base/src/console.ts#L42). This module, hooks into the [ConsoleManager](https://github.com/travetto/travetto/tree/main/module/base/src/console.ts#L42) and receives all logging events from all files compiled by the [Travetto](https://travetto.dev). | ||
| All of the logging instrumentation occurs at transpilation time. All `console.*` methods are replaced with a call to a globally defined variable that delegates to the [ConsoleManager](https://github.com/travetto/travetto/tree/main/module/base/src/console.ts). This module, hooks into the [ConsoleManager](https://github.com/travetto/travetto/tree/main/module/base/src/console.ts) and receives all logging events from all files compiled by the [Travetto](https://travetto.dev). | ||
| A sample of the instrumentation would be: | ||
@@ -231,3 +220,2 @@ | ||
| ### Filtering Debug | ||
| The `debug` messages can be filtered using the patterns from the [debug](https://www.npmjs.com/package/debug). You can specify wild cards to only `DEBUG` specific modules, folders or files. You can specify multiple, and you can also add negations to exclude specific packages. | ||
@@ -237,2 +225,3 @@ | ||
| ```bash | ||
| # Debug | ||
@@ -249,2 +238,3 @@ $ DEBUG=-@travetto/model npx trv run app | ||
| ```bash | ||
| # Debug | ||
@@ -256,4 +246,2 @@ $ DEBUG=express:*,@travetto/rest npx trv run rest | ||
| The [StreamUtil](https://github.com/travetto/travetto/tree/main/module/base/src/stream.ts#L15) class provides basic stream utilities for use within the framework: | ||
| * `toBuffer(src: Readable | Buffer | string): Promise<Buffer>` for converting a stream/buffer/filepath to a Buffer. | ||
@@ -267,4 +255,2 @@ * `toReadable(src: Readable | Buffer | string):Promise<Readable>` for converting a stream/buffer/filepath to a Readable | ||
| Simple functions for providing a minimal facsimile to [lodash](https://lodash.com), but without all the weight. Currently [ObjectUtil](https://github.com/travetto/travetto/tree/main/module/base/src/object.ts#L10) includes: | ||
| * `isPrimitive(el)` determines if `el` is a `string`, `boolean`, `number` or `RegExp` | ||
@@ -279,8 +265,7 @@ * `isPlainObject(obj)` determines if the obj is a simple object | ||
| Data utilities for binding values, and type conversion. Currently [DataUtil](https://github.com/travetto/travetto/tree/main/module/base/src/data.ts#L9) includes: | ||
| * `deepAssign(a, b, mode ?)` which allows for deep assignment of `b` onto `a`, the `mode` determines how aggressive the assignment is, and how flexible it is. `mode` can have any of the following values: | ||
| * `deepAssign(a, b, mode ?)` which allows for deep assignment of `b` onto `a`, the `mode` determines how aggressive the assignment is, and how flexible it is. `mode` can have any of the following values: | ||
| * `loose`, which is the default is the most lenient. It will not error out, and overwrites will always happen | ||
| * `coerce`, will attempt to force values from `b` to fit the types of `a`, and if it can't it will error out | ||
| * `strict`, will error out if the types do not match | ||
| * `coerceType(input: unknown, type: Class<unknown>, strict = true)` which allows for converting an input type into a specified `type` instance, or throw an error if the types are incompatible. | ||
@@ -292,4 +277,2 @@ * `shallowClone<T = unknown>(a: T): T` will shallowly clone a field | ||
| Common utilities used throughout the framework. Currently [Util](https://github.com/travetto/travetto/tree/main/module/base/src/util.ts#L14) includes: | ||
| * `uuid(len: number)` generates a simple uuid for use within the application. | ||
@@ -304,3 +287,3 @@ * `allowDenyMatcher(rules[])` builds a matching function that leverages the rules as an allow/deny list, where order of the rules matters. Negative rules are prefixed by '!'. | ||
| const tpl = makeTemplate((name: 'age'|'name', val) => `**${name}: ${val}**`); | ||
| tpl`{{age:20}} {{name: 'bob'}}`; | ||
| tpl`{{age:20}} {{name: 'bob'}}</>; | ||
| // produces | ||
@@ -311,5 +294,4 @@ '**age: 20** **name: bob**' | ||
| ## Time Utilities | ||
| [TimeUtil](https://github.com/travetto/travetto/tree/main/module/base/src/time.ts#L23) contains general helper methods, created to assist with time-based inputs via environment variables, command line interfaces, and other string-heavy based input. | ||
| [TimeUtil](https://github.com/travetto/travetto/tree/main/module/base/src/time.ts#L23) contains general helper methods, created to assist with time-based inputs via environment variables, command line interfaces, and other string-heavy based input. | ||
| **Code: Time Utilities** | ||
@@ -417,3 +399,2 @@ ```typescript | ||
| ## Shutdown Management | ||
| Another key lifecycle is the process of shutting down. The framework provides centralized functionality for running operations on shutdown. Primarily used by the framework for cleanup operations, this provides a clean interface for registering shutdown handlers. The code overrides `process.exit` to properly handle `SIGKILL` and `SIGINT`, with a default threshold of 3 seconds. In the advent of a `SIGTERM` signal, the code exits immediately without any cleanup. | ||
@@ -420,0 +401,0 @@ |
| import timers from 'timers/promises'; | ||
| import { RootIndex, WatchEvent, watchFolders } from '@travetto/manifest'; | ||
| import { ManifestModuleUtil, RootIndex, WatchEvent, watchFolders } from '@travetto/manifest'; | ||
@@ -84,3 +84,6 @@ import { ObjectUtil } from '../object'; | ||
| (ev, folder) => this.dispatch(ev, folder), | ||
| { filter: ev => ev.file.endsWith('.js'), createMissing: true } | ||
| { | ||
| filter: ev => ManifestModuleUtil.getFileType(ev.file) === 'js', | ||
| createMissing: true | ||
| } | ||
| ); | ||
@@ -87,0 +90,0 @@ } |
@@ -53,3 +53,3 @@ import { Readable } from 'stream'; | ||
| if (cfg.includeCommon) { | ||
| paths.unshift(...GlobalEnv.resourcePaths, path.resolve('resources')); | ||
| paths.unshift(...GlobalEnv.resourcePaths, path.resolve('resources'), '@#resources'); | ||
| } | ||
@@ -56,0 +56,0 @@ const found = new Set(); |
@@ -42,2 +42,2 @@ /* eslint-disable @typescript-eslint/no-explicit-any */ | ||
| entries<K extends Record<symbol | string, unknown>>(record: K): [keyof K, K[keyof K]][]; | ||
| } & ObjectConstructor = Object; | ||
| } & ObjectConstructor = Object; |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by0.04%
101113
- Lines of code
- increased by0.09%
2188
Worsened metrics
- Number of lines in readme file
- decreased by-4.58%
396
Dependency changes
Updated@travetto/manifest@^3.0.3