# JavaScript

> Use the justlog3 npm package to log to a file and JustLog3 Cloud from JavaScript or TypeScript.

The `justlog3` npm package writes log lines to a file and, once you set an API token, sends them to JustLog3 Cloud.

## Install

```bash
npm install justlog3
```

Node.js 18 or newer. The package supports ESM and CommonJS and includes TypeScript types. Source: [github.com/OAzizjon/justlog3](https://github.com/OAzizjon/justlog3/tree/main/js). License: MIT.

Import the API with ESM:

```javascript
import { Logger, BasicLogger, setApiToken, shutdown } from 'justlog3'
```

Or CommonJS:

```javascript
const { Logger, BasicLogger, setApiToken, shutdown } = require('justlog3')
```

## Log to a file

```javascript
import { Logger } from 'justlog3'

const logger = new Logger('app.log')

logger.log('Hi...')
logger.log('debug', { offConsole: true })
logger.log('There is some error!', { red: true })
logger.log('OK', { green: true })
logger.log('There is a critical error!', { red: true, customPrefix: 'CRITICAL!!' })
```

`.log` is added to the filename if it is missing. The console shows colored lines; `app.log` gets one line per call with a prefix and a local timestamp with milliseconds:

```text
GREY:2026-10-05 14:03:12.517 - Hi...
```

With `withTime: false`, lines have no timestamp:

```text
GREY: Hi...
```

An `Error` passed to `log()` is written with its stack trace. Other objects are formatted on one line with `util.inspect`.

## Send to JustLog3 Cloud

```javascript
import { Logger, setApiToken } from 'justlog3'

setApiToken(process.env.JUSTLOG3_TOKEN, { url: 'https://jl3-cloud.site/api/logs/' })
const logger = new Logger('app.log')
logger.log('This line goes to the file and to the cloud')
```

Call `setApiToken()` once, before or after creating loggers. Keep the token in an environment variable rather than in code.

- Lines are sent every 5 seconds, or sooner once 75 lines are waiting.
- A request carries at most 5,000 lines and 512 KB of text; bodies from 1 KB are gzip-compressed.
- Each logger keeps up to 10,000 unsent lines; beyond that the oldest are dropped with a single warning.
- No answer or HTTP 5xx: the batch is resent with the same sequence number. The wait starts at 5 s and doubles up to 5 minutes.
- HTTP 429: nothing is sent until `Retry-After`; lines stay buffered.
- HTTP 401 / 403: cloud sending stops, files keep being written. Call `setApiToken()` again with a valid token.
- HTTP 413: later batches carry fewer lines.

Cloud options: `url`, `flushIntervalMs` (default 5,000), `timeoutMs` (default 5,000), and `maxBatchLines` (default 5,000).

## Levels

```javascript
import { BasicLogger } from 'justlog3'

const logger = new BasicLogger('app.log', { consoleLevel: 'INFO' })
logger.debug('cache warmed')
logger.info('server started')
logger.success('processed items')
logger.warning('disk 85% full')
logger.error('payment failed')
logger.critical('database is down')
```

`BasicLogger` has `debug`, `info`, `success`, `warning`, `error`, and `critical` methods. `consoleLevel` only filters the console. Every line still goes to the file and the cloud.

## Shutdown

- On a normal exit, a `beforeExit` hook flushes files and sends what is left, bounded by `timeoutMs`.
- No signal handlers are installed. In containers, add a handler to flush before exiting:

```javascript
import { shutdown } from 'justlog3'

process.on('SIGTERM', async () => {
  await shutdown()
  process.exit(0)
})
```

`process.exit()` skips `beforeExit`, so call `await shutdown()` before it. Use `file: false` for serverless environments.

## Logger options

```javascript
new Logger('app.log', {
  withTime: true,
  filemode: 'a',
  cycles: 50,
  cloudCycles: 75,
  file: true,
})
```

Use `.flush()` to flush a logger's buffered lines. Loggers also provide `.status()`. If a disk write fails (disk full, file locked), the error and the unwritten lines are printed to the console instead of being thrown from `log()`.

| Option | Default | Meaning |
|---|---|---|
| `withTime` | `true` | Include a local timestamp with milliseconds in every line |
| `filemode` | `'a'` | `'w'` truncates the file on creation |
| `cycles` | `50` | Lines per disk write |
| `cloudCycles` | `75` | Waiting lines that wake the cloud sender |
| `file` | `true` | Write log lines to a file |
| `consoleLevel` | `'DEBUG'` | `BasicLogger` only; filters console output |

`Logger.log(message, { red, green, customPrefix, offConsole })` sets the line color, prefix, and console visibility.