# phat-event

> Event logs

Latest version **1.1.2** (published 2019-11-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install phat-event
pnpm add phat-event
yarn add phat-event
bun add phat-event
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.2 |
| Published | 2019-11-04 |
| First published | 2019-11-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 14 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Lou Bichard |
| Maintainers | loujaybee |
| Keywords | logging |

## Links

- npm: https://www.npmjs.com/package/phat-event
- Repository: https://github.com/loujaybee/phat-event
- Homepage: https://github.com/loujaybee/phat-event#readme
- Issues: https://github.com/loujaybee/phat-event/issues
- npm.io page: https://npm.io/package/phat-event

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 1.1.2 (latest) — 2019-11-04
- 1.1.1 — 2019-11-01
- 1.1.0 — 2019-11-01
- 1.0.0 — 2019-11-01

## README

**PLEASE NOTE** Phat-event is a beta library, currently under development.

## Phat Event

phat-event is a JavaScript-based library designed for easier creation of "phat", one-per-service log events.

phat-event works well in serverless environments.

## Motivation

There are no (that I'm aware of) opinionated log event construction libraries.

## What's the difference between this and Winston, Bunyan, X

phat-event is not a logging library. The library takes a configuration function which is called with the constructed event.

Phat event is primarily for the _opinionated_ construction of a fat single log line entry, it is not for the act of logging.

## Getting Started

Install: `npm install phat-event`

```javascript
const PhatEvent = require("phat-event");
const phatEvent = new PhatEvent();
const mockLog = jest.fn();

phatEvent.configure({ log: console.log })

phatEvent
    .addKey('key', true)

phatEvent
    .emit();
```

## What is a log event?

A log event is a form of structured log, that is updated throughout the lifecycle of a service and a single structured event is emitted at the end of the service.

Rather than this:

```javascript
{ "timestamp": "X", "message": "Something" }
```

You have this:

```javascript
{
    "timestamp": "X",
    "step1": {
        "input": {
            ...
        }
        "output": {
            ...
        }
    }
}
 ```

## The difficulty with log events

But log events have downsides.

* If the service fails unexpectedly, the event might not be emitted.
* Each emitted property is not timestamped by default
* Poor naming of properties makes it harder to understand property meanings
* There is no "standard" way to structure these fat log events

## Why log events > individual structure logs

Log events allow you to analyse across datapoints without clever tooling that rolls up based on a log property, such as a correlation ID.

## API

Documentation for the public API of phat-event.

### .configure({ log })

The configure method takes an object of configuration properties, such as:

* `log` — The method that is called when the `emit` event is triggered.

### .addKey(String, Any)

Adds a key and value to the event object.

Nested properties can be passed by using dot delimiters between keys `prop.prop.prop`.

### .sanitise(String)

Convers

### .emit()

Invokes the configured `log` method and applies the event as the first argument.

This method allows the log entry to be emitted at the end of service processing.

## Releases

### 1.1.2

* Return the constructor, rather than the object instance

### 1.1.1

* Bugfix to allow `.sanitise` to access deeply nested properties.

### 1.1.0

* Implements `.sanitise`
    * A helper method which implements method to block out large or sensitive properties.

### 1.0.0

* Implements `push` method

## Where does the name come from?

Naming things is hard. And something dry like "event emitter" or similiar isn't noteworthy enough.

As a topic discussed heavily by Charity Majors, I stole the name from her tweet thread: [this tweet thread comment](https://twitter.com/mipsytipsy/status/1042978722645569537) where she refers to the event objects as "phat", which made me laugh and is now the name of this library.

---
_Source: https://npm.io/package/phat-event · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._