time-window-classifier

Reference CLI showing how to apply day-boundary to line-delimited operational event data.

Intent

This repository exists as a reference implementation for one concrete use of day-boundary in an end-to-end workflow:

• read operational events from JSONL
• resolve each event into a business window using a non-midnight boundary
• show the difference between calendar-day grouping and operational-window grouping

The point is not to build a full product. The point is to show how day-boundary can sit inside a practical JSONL processing flow with a compact but deliberately edge-case-heavy reference input.

day-boundary models an operational day as a rolling window anchored to a configurable boundary time, rather than a fixed midnight-to-midnight calendar day.

What the CLI does

The CLI reads a JSONL file, extracts a timestamp field, and classifies each event into a day-boundary window for a configured time zone and boundary time.

The CLI does not implement boundary logic itself. It delegates operational-window resolution to day-boundary and focuses on file input, output formatting, and reference reporting.

This CLI is designed to fit into JSONL-based data pipelines. It reads line-delimited JSON from a file or stdin and writes results to stdout.

Supported output modes:

• report: human-readable comparison between naive calendar grouping and operational-window grouping
• annotate: JSONL output with window metadata added to each record
• summary: JSONL output grouped by resolved operational window

Why this repo includes this input

The included input is intentionally small and crosses the Europe/London DST fallback boundary.

That gives the reference input two useful properties:

• some events occur after local midnight but still belong to the prior operational window
• one resolved window is 25 hours long, which shows why this should not be modeled as a fixed midnight-to-midnight day

Project layout

• bin/time-window-classifier.js: CLI entry point
• reference-data/events.jsonl: reference input data
• CHANGELOG.md: version notes

Run

Install dependencies:

npm install

This installs the reference CLI dependencies, including day-boundary as the core operational-window engine used by the CLI.

Run the default report:

node ./bin/time-window-classifier.js --input ./reference-data/events.jsonl --time-zone Europe/London --boundary 09:00

Read from stdin instead of a file:

Get-Content ./reference-data/events.jsonl | node ./bin/time-window-classifier.js --input - --time-zone Europe/London --boundary 09:00

Example report excerpt:

Naive Calendar Grouping
=======================
Local date    Event count
2026-10-24    1
2026-10-25    5

Operational Window Grouping
===========================
Window                                             Hours  Events
2026-10-24 09:00 +01:00 -> 2026-10-25 09:00 +00:00  [25h]  4
2026-10-25 09:00 +00:00 -> 2026-10-26 09:00 +00:00  24h    2

Example annotate output:

{"eventId":"scan-002","timestamp":"2026-10-25T00:30:00Z","site":"london-hub","event":"badge-scan","windowId":"2026-10-24T09:00:00+01:00[Europe/London]__2026-10-25T09:00:00+00:00[Europe/London]","windowStart":"2026-10-24T09:00:00+01:00[Europe/London]","windowEnd":"2026-10-25T09:00:00+00:00[Europe/London]","windowLabel":"2026-10-24T09:00:00+01:00[Europe/London] -> 2026-10-25T09:00:00+00:00[Europe/London]","classifiedInstant":"2026-10-25T00:30:00Z"}

Run the packaged reference command:

npm run reference:report

Alternative output modes are available through --mode when you need JSONL output instead of the default report.

If you want the shorter twc command locally, link the package first:

npm link
twc --input ./reference-data/events.jsonl --time-zone Europe/London --boundary 09:00

CLI

node ./bin/time-window-classifier.js --input <file.jsonl|-> --time-zone <IANA zone> --boundary <HH:MM> [options]

Options:

• --mode report|annotate|summary
• --timestamp-field <name>
• --help

Expected input

Input must be JSONL. Each line must be a valid JSON object containing a timestamp field.

Default timestamp field:

{"timestamp":"2026-10-25T08:45:00Z"}

Override the field name when needed:

node ./bin/time-window-classifier.js --input ./events.jsonl --time-zone Europe/London --boundary 09:00 --timestamp-field occurredAt

Why this reference exists

This repo is most useful when you want to show that operational reporting often does not align with calendar dates. The default report mode is the shortest path to that comparison, while annotate and summary are there to inspect the exact classification output.