sleep-compiler

1.4.0 verified Fri May 01 auth: no javascript

A command-line sleep tracker that logs, analyzes, and reports sleep patterns. Version 1.4.0 is the latest stable release. Data is stored locally in SQLite at ~/.sleep-compiler/sleep.db with no cloud dependencies. Key differentiators: it operates entirely offline, supports active sleep sessions (sleep now / wake now), generates reports with quality thresholds and consistency scores, and exports CSV. Alternatives like Sleep as Android require a mobile app; sleep-compiler runs in the terminal for developers and privacy-conscious users.

Common errors

error Error: No pending sleep found. Run `sleep-compiler sleep now` first. ↓

cause Attempted to run `wake now` without an active sleep session.

fix

Start a sleep session with sleep-compiler sleep now before calling wake now.

error SyntaxError: Cannot use import statement outside a module ↓

cause Trying to use ESM imports in a CommonJS context without proper configuration.

fix

Add "type": "module" to package.json or rename file to .mjs.

error Error: Invalid sleep time format. Use HH:MM in 24h format. ↓

cause Provided sleep or wake time in wrong format, e.g., using 12-hour with AM/PM.

fix

Use 24-hour format: hours 00-23, minutes 00-59. Example: '23:30'.

Warnings

breaking In v1.4.0, the API changed from CommonJS to ESM-only. require() will throw an error. ↓

fix Use import statements instead of require(). Update your package.json to include "type": "module" or use .mjs extension.

gotcha The `sleep now` command saves a pending session to ~/.sleep-compiler/pending-sleep.json. If this file is deleted before running `wake now`, the session is lost. ↓

fix Do not manually modify or delete files in ~/.sleep-compiler/. Use the status command to check active sessions.

gotcha Times must be in 24-hour format (HH:MM). Using 12-hour format with AM/PM will cause parsing errors. ↓

fix Always provide times in 24-hour format, e.g., '23:30' for 11:30 PM or '07:15' for 7:15 AM.

deprecated The `--format csv` option for export was added in v1.3.0 and is stable. The old export command without format is deprecated. ↓

fix Use `sleep-compiler export --format csv` instead of `sleep-compiler export`.

Install

npm install sleep-compiler

yarn add sleep-compiler

pnpm add sleep-compiler

Imports

default

wrong

const sleepCompiler = require('sleep-compiler')

correct

import sleepCompiler from 'sleep-compiler'

Package is ESM-only as of v1.4.0

logSleep

wrong

import logSleep from 'sleep-compiler'

correct

import { logSleep } from 'sleep-compiler'

Named export, not default

getReport

wrong

const getReport = require('sleep-compiler').getReport

correct

import { getReport } from 'sleep-compiler'

ESM named import; CommonJS require will fail

Quickstart

Demonstrates logging a sleep entry and retrieving a report programmatically using named imports.

// Log sleep entry and generate a 7-day report
import { logSleep, getReport } from 'sleep-compiler';

async function main() {
  // Log sleep for last night
  await logSleep({
    sleepTime: '23:30',
    wakeTime: '07:15',
    date: '2024-03-15'
  });

  // Get report for last 7 days
  const report = await getReport({ days: 7 });
  console.log(report);
}

main().catch(err => console.error(err));