Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .prettierignore
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
dist
CHANGELOG.md
pnpm-lock.yaml
README.md
coverage
.pnpm-store
.pnpm
Expand Down
7 changes: 7 additions & 0 deletions packages/commitlint-config/README.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,27 @@
# commitlint-config

Common commitlint configuration for MapColonies projects

## Installation

To install the package run the following command:

```bash
npm install --save-dev @mapcolonies/commitlint-config
```

## Usage

To use the package, create a `commitlint.config.js` file in the root of your project and add the following code:

```javascript
module.exports = {
extends: ['@mapcolonies/commitlint-config'],
};
```

## Rules

This package extends all the rules from the `@commitlint/config-conventional` package and adds the following rules:

1. The allowed values for the type parameters (feat,fix,chore..) are as follow: `deps`, `helm`, `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`
9 changes: 7 additions & 2 deletions packages/error-express-handler/README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,19 @@
# error-express-handler

This package exports a middleware for express that handles Error and HttpError(custom package type).

## Install

```sh
npm install --save @map-colonies/error-express-handler
```

## API documentation

Check the autogenerated documentation [here](https://mapcolonies.github.io/infra-packages/modules/_map-colonies_error-express-handler.html).

## Usage

Add the handler as the last middleware, so any error forwarded by the controllers will be handled.
If the value of `NODE_ENV` is production the error message will be redacted and a generic one will be sent instead.
In development, in addition to the error message, the stack trace of the error will be included in the response.
Expand All @@ -26,12 +30,13 @@ app.use('/meow', fn);

app.use(getErrorHandlerMiddleware());

app.listen(8080, function() {
console.log('server is up');
app.listen(8080, function () {
console.log('server is up');
});
```

## Flow

```mermaid
flowchart TD
A@{ label: "NODE_ENV='production'" } -- true --> B["error implements HttpError"]
Expand Down
8 changes: 5 additions & 3 deletions packages/eslint-config/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,23 @@ The package only supports eslint 9 and above using the flat configuration.
## Installation

### base

```bash
$ npm install --save-dev eslint @map-colonies/eslint-config
```

### react

```
$ npm install --save-dev @map-colonies/eslint-config eslint-plugin-react eslint-plugin-react-hooks
```

### jest

```
$ npm install --save-dev @map-colonies/eslint-config eslint-plugin-jest
```


## Usage

Add the configs you want to the eslint configuration file of your choice. In this example we are using the file `eslint.config.mjs`
Expand All @@ -40,10 +42,10 @@ import tsBaseConfig from '@map-colonies/eslint-config/ts-base';
import { config } from '@map-colonies/eslint-config/helpers';

export default config(tsBaseConfig);

```

## Debug

If you want to check the ESLint configuration, debug problems or just see the final configuration, you can the following command that will open the eslint configuration UI in your browser.

```bash
Expand All @@ -52,7 +54,6 @@ npx eslint --inspect-config .

For more information check the following link [debug](https://eslint.org/docs/latest/use/configure/debug).


## Adding new Configs

Add a new file and name it as you would like. Inside export the ESLint configuration.
Expand All @@ -76,4 +77,5 @@ $ npx eslint --print-config index.ts
Don't forget adding the config to this readme :blush:

## Issues

If any linting error is appearing twice, or you have any other problem, please open an issue with all the details you have.
30 changes: 15 additions & 15 deletions packages/express-access-log-middleware/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
An access and error logger for express based on [pino-http](https://github.com/pinojs/pino-http).

## API documentation

Check the autogenerated documentation [here](https://mapcolonies.github.io/infra-packages/modules/_map-colonies_express-access-log-middleware.html).

## Usage
Expand All @@ -12,14 +13,14 @@ import * as express from 'express';
import { jsLogger } from '@map-colonies/js-logger';
import { httpLogger } from '@map-colonies/express-access-log-middleware';

const app = express()
const app = express();

const logger = jsLogger();

app.use(httpLogger({logger}));
app.use(httpLogger({ logger }));

app.get('/', (req,res) => {
res.json({hello: 'world'});
app.get('/', (req, res) => {
res.json({ hello: 'world' });
});

app.listen(8080);
Expand All @@ -30,15 +31,14 @@ for more detailed usage check the [pino-http documentation](https://github.com/p
###

## Configuration
| name | type | default value | description |
|---|---|---|---|
| logger | Logger | required | The logger instance used for logging requests and responses |
| ignorePaths | (string \| RegExp)[] | undefined | Array of paths or regular expressions to ignore from logging |
| ignore | AutoLoggingOptions['ignore'] | undefined | Custom ignore options for automatic logging |
| customLogLevel | (req, res, err) => LogLevel | error for >=400, info otherwise | Custom function to determine log level based on request, response and error |
| customSuccessMessage | (res: ServerResponse) => string | undefined | Custom function to generate success messages |
| customSuccessObject | (req: IncomingMessage, res: ServerResponse, val: any) => object | undefined | Custom function to modify the success log object |
| customErrorMessage | (error: Error, res: ServerResponse) => string | undefined | Custom function to generate error messages |
| customErrorObject | (req: IncomingMessage, res: ServerResponse, error: Error) => object | undefined | Custom function to modify the error log object |


| name | type | default value | description |
| -------------------- | ------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------- |
| logger | Logger | required | The logger instance used for logging requests and responses |
| ignorePaths | (string \| RegExp)[] | undefined | Array of paths or regular expressions to ignore from logging |
| ignore | AutoLoggingOptions['ignore'] | undefined | Custom ignore options for automatic logging |
| customLogLevel | (req, res, err) => LogLevel | error for >=400, info otherwise | Custom function to determine log level based on request, response and error |
| customSuccessMessage | (res: ServerResponse) => string | undefined | Custom function to generate success messages |
| customSuccessObject | (req: IncomingMessage, res: ServerResponse, val: any) => object | undefined | Custom function to modify the success log object |
| customErrorMessage | (error: Error, res: ServerResponse) => string | undefined | Custom function to generate error messages |
| customErrorObject | (req: IncomingMessage, res: ServerResponse, error: Error) => object | undefined | Custom function to modify the error log object |
28 changes: 16 additions & 12 deletions packages/js-logger/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
JavaScript and TypeScript logger for MapColonies based on pino.

## API documentation

Check the autogenerated documentation [here](https://mapcolonies.github.io/infra-packages/modules/_map-colonies_js-logger.html).

## Usage
Expand All @@ -14,34 +15,37 @@ const logger = jsLogger();

logger.info('hello world');

logger.error({hello: 'world'});
logger.error({ hello: 'world' });
```

### Logging errors

One of the features of the logger is the ability to parse error objects and format them accordingly.
To allow the logger to identify the error, add it to the log object under the `err` key.

```typescript
try {
// complex code
} catch (error) {
logger.error({msg: "oh noes", err: error});
logger.error({ msg: 'oh noes', err: error });
}
```

For more detailed usage check the [pino documentation](https://github.com/pinojs/pino).

## Configuration
| name | type | default value | description |
|---|---|---|---|
| enabled | boolean | true | determines if logging is enabled |
| level | string | 'info' | specifies the logging level |
| redact | array | undefined | defines paths to redact from log output |
| hooks | object | undefined | hooks for customizing log behavior |
| base | object | {pid: process.pid, hostname: os.hostname} | base properties to include in log output |
| mixin | function | undefined | function to add custom properties to log output |
| prettyPrint | boolean | false | enables pretty-printing of log output |
| pinoCaller | boolean | false | includes the caller's file and line number in log output |

| name | type | default value | description |
| ----------- | -------- | ----------------------------------------- | -------------------------------------------------------- |
| enabled | boolean | true | determines if logging is enabled |
| level | string | 'info' | specifies the logging level |
| redact | array | undefined | defines paths to redact from log output |
| hooks | object | undefined | hooks for customizing log behavior |
| base | object | {pid: process.pid, hostname: os.hostname} | base properties to include in log output |
| mixin | function | undefined | function to add custom properties to log output |
| prettyPrint | boolean | false | enables pretty-printing of log output |
| pinoCaller | boolean | false | includes the caller's file and line number in log output |

### OpenTelemetry log support

js-logger can emit logs in OpenTelemetry format for integration with OpenTelemetry-compatible observability tools.
22 changes: 11 additions & 11 deletions packages/openapi-express-viewer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ A lightweight Express.js middleware for serving OpenAPI/Swagger documentation wi
- TypeScript support out of the box

## API documentation
Check the autogenerated documentation [here](https://mapcolonies.github.io/infra-packages/modules/_map-colonies_openapi-express-viewer.html).

Check the autogenerated documentation [here](https://mapcolonies.github.io/infra-packages/modules/_map-colonies_openapi-express-viewer.html).

## Installation

Expand All @@ -31,8 +31,8 @@ const app = express();

const config = {
filePathOrSpec: './openapi.yml', // Path to your OpenAPI spec file
uiPath: '/api-docs', // UI endpoint
rawPath: '/spec' // Raw spec endpoint
uiPath: '/api-docs', // UI endpoint
rawPath: '/spec', // Raw spec endpoint
};

const openapiRouter = new OpenapiViewerRouter(config);
Expand All @@ -51,14 +51,14 @@ const openapiSpec = {
openapi: '3.0.0',
info: {
title: 'My API',
version: '1.0.0'
}
version: '1.0.0',
},
// ... rest of your OpenAPI specification
};

const config = {
filePathOrSpec: openapiSpec,
uiPath: '/api-docs'
uiPath: '/api-docs',
};

const openapiRouter = new OpenapiViewerRouter(config);
Expand All @@ -67,11 +67,11 @@ const openapiRouter = new OpenapiViewerRouter(config);

## Configuration Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `filePathOrSpec` | `string \| object` | Yes | Path to OpenAPI spec file or specification object |
| `uiPath` | `string` | Yes | Endpoint path for Swagger UI |
| `rawPath` | `string` | No | Endpoint path for raw specification files |
| Option | Type | Required | Description |
| ---------------- | ------------------ | -------- | ------------------------------------------------- |
| `filePathOrSpec` | `string \| object` | Yes | Path to OpenAPI spec file or specification object |
| `uiPath` | `string` | Yes | Endpoint path for Swagger UI |
| `rawPath` | `string` | No | Endpoint path for raw specification files |

### Endpoints

Expand Down
Loading
Loading