# @bigscreen/lib

The bedrock shared library — logging, Redis, Postgres, secrets, hashing, time, express helpers. Every service imports from here.

**Path:** [lib/](../../lib).
**Package name:** `@bigscreen/lib`.
**Entry:** [lib/index.ts](../../lib/index.ts).

## Module Map

```mermaid
flowchart TB
    subgraph Logging["Logging & telemetry"]
        LOG[Logger]
        LDB[LogDatabase]
    end

    subgraph State["State / I-O"]
        RED[Redis]
        PG[PostgresDatabase]
        DBU[DatabaseUtils]
        DDOC[DocumentDatabase]
    end

    subgraph Utilities
        HU[HashUtils]
        FU[Formatters]
        EU[ExpressUtils]
        TU[TimeUtils]
        U[Utils]
        PU[ProcessUtils]
        SEC[SecretsLoader]
    end

    RED -.uses Redlock.-> RED
    PG -.uses pg pool.-> PG
    LOG -.uses Pino +<br/>Winston + Discord.-> LOG
    DDOC -.uses Firestore /<br/>alt document store.-> DDOC
```

All of these are exported from [lib/index.ts](../../lib/index.ts):

```ts
export { Logger, LogDatabase } from "./Logger";
export * as HashUtils from "./HashUtils";
export * as Formatters from "./Formatters";
export * as ExpressUtils from "./ExpressUtils";
export * as DocumentDatabase from "./DocumentDatabase";
export * as TimeUtils from "./TimeUtils";
export * as Utils from "./Utils";
export * as ProcessUtils from "./ProcessUtils";
export { Redis, RedisInitRequest, RedisClient } from "./Redis";
export * as PostgresDatabase from "./PostgresDatabase";
export * as DatabaseUtils from "./DatabaseUtils";
```

`SecretsLoader` and the `DiscordLogger` namespace hang off the same tree (imported as `@bigscreen/lib/SecretsLoader` and `@bigscreen/lib/Logger` respectively).

## What Each Module Does

### `Logger`

Structured logging backed by Pino. Emits to:

- **stdout** (Pino's JSON format, or pino-pretty in dev)
- **CloudWatch** (via `winston-cloudwatch`)
- **Discord** (webhooks, via the `DiscordLogger` sub-namespace)

`DiscordLogger.info(source, message)` / `.error(source, err)` take a `Source` enum (e.g. `Fabricator`, `Auth`) that picks the right webhook. This is used heavily by `apps/admin_api` worker completions.

### `Redis`

Thin wrapper around `ioredis`. Key features:

- Connection factory via `Redis.initialize()` — returns a `RedisClient` that each service stashes.
- **Redlock integration** — distributed locks with a 5 s default TTL. Used anywhere concurrent mutations must serialise (room creation, user admission, media-server updates).
- Standard helpers: `get`, `set`, `hset`, `hgetall`, `del`, pub/sub wrappers.

### `PostgresDatabase`

Pool-based Postgres client. Exposes connection factories and a few query helpers. `DatabaseUtils` adds SQL string-building helpers on top.

### `DocumentDatabase`

Abstraction over a document store (Firestore historically; sometimes used for event logs or less-relational data).

### `HashUtils`

Random-id generation (`generateRandomId2`), hashing, sometimes short-id generators for shareable links.

### `Formatters`

Formatting helpers — phone numbers, addresses, currencies, timestamps in display form.

### `TimeUtils`

Wrapper around `date-fns` with Bigscreen-preferred patterns.

### `Utils`

Miscellaneous lodash-style helpers that didn't warrant their own module.

### `ProcessUtils`

Node process helpers — signal handling, graceful shutdown orchestration.

### `ExpressUtils`

Express middleware snippets shared across the three REST services (IP extraction, error shape normalisation, etc).

### `SecretsLoader`

Loads runtime secrets from AWS Secrets Manager. Services call this during boot to populate env-like values that shouldn't be baked into the .env file.

## How services use it

Every service's first import line is roughly:

```ts
import { Logger, Redis, PostgresDatabase } from "@bigscreen/lib";
```

By the time routes start registering, `Logger` is initialised, the Redis connection is live, and the Postgres pool is warm. See any service doc's "Startup" section for the exact boot order.