Parse Time Value

`parseMSec`

Converts time values with units to milliseconds or seconds.

The parseMSec function parses time strings with units (like "2h", "30m", "1.5d") or numeric values into milliseconds or seconds. It's useful for handling time durations in configuration files, command-line arguments, or any scenario where human-readable time strings need to be converted to programmatic time values.

Import

import { parseMSec } from "toolbox-x/utils";

Function Signature

parseMSec(value: TimeWithUnit | Numeric, sec?: boolean): number

Parameters

Parameter	Type	Default	Description
`value`	`TimeWithUnit \| Numeric`	-	The time value to parse. Can be a string with unit, number, or numeric string.
`sec`	`boolean`	`false`	When `true`, returns the value in seconds instead of milliseconds.

Returns

number - The parsed time value in milliseconds (or seconds if sec is true)
NaN - If the input cannot be parsed

Supported Units

Unit	Variants
Year	`y`, `yr`, `yrs`, `year`, `years`
Month	`mo`, `month`, `months`
Week	`w`, `week`, `weeks`
Day	`d`, `day`, `days`
Hour	`h`, `hr`, `hrs`, `hour`, `hours`
Minute	`m`, `min`, `mins`, `minute`, `minutes`
Second	`s`, `sec`, `secs`, `second`, `seconds`
Millisecond	`ms`, `msec`, `msecs`, `millisecond`, `milliseconds`

Type Definitions

type Numeric = number | `${number}`;

type $TimeUnitVar = "year" | "y" | "yr" | "yrs" | "years" | "month" | "mo" | "months" | "week" | "w" | "weeks" | "day" | "d" | "days" | "hour" | "h" | "hr" | "hrs" | "hours" | "minute" | "m" | "min" | "mins" | "minutes" | "second" | "s" | "sec" | "secs" | "seconds" | "millisecond" | "ms" | "msec" | "msecs" | "milliseconds";

type $UnitAnyCase = Capitalize<$TimeUnitVar> | Uppercase<$TimeUnitVar> | $TimeUnitVar;

type TimeWithUnit = `${number}${$UnitAnyCase}` | `${number} ${$UnitAnyCase}`;

Usage Examples

playground.ts

Input Format Rules

Valid Inputs

Time strings with units:

parseMSec('10ms')     // Valid
parseMSec('30s')      // Valid
parseMSec('1.5d')     // Valid (decimal values)

Numeric values:

parseMSec(60)         // Valid (treated as 60 seconds)
parseMSec('120')      // Valid (treated as 120 seconds)
parseMSec(2.5)        // Valid (treated as 2.5 seconds)

Invalid Inputs

parseMSec('')            // NaN (empty string)
parseMSec('unknown')     // NaN (no numeric value)
parseMSec('120 unknown') // NaN (unknown unit)
parseMSec('2h30m')       // NaN (combined units)
parseMSec('1d 6h')       // NaN (spaces allowed)
parseMSec('ms')          // NaN (missing numeric value)
parseMSec(null)          // NaN (not a valid type)
parseMSec(undefined)     // NaN (not a valid type)

Error Handling

Input Validation

The function performs several layers of validation:

// Type validation
parseMSec('2h');         // Valid: returns 7200000
parseMSec('invalid');    // Invalid: returns NaN

// String length validation
parseMSec('1h');         // Valid
parseMSec('a'.repeat(100)); // Throws RangeError

// Unit validation
parseMSec('10ms');       // Valid
parseMSec('10years');    // Valid

Error Recovery

function safeParseMSec(value: unknown, sec = false): number {
  try {
    const result = parseMSec(value as any, sec);
    if (isNaN(result)) {
      console.warn(`Could not parse time value: ${value}`);
      return sec ? 0 : 0; // Return default
    }
    return result;
  } catch (error) {
    console.error('Error parsing time:', error);
    return sec ? 0 : 0; // Return default on error
  }
}

Performance Considerations

Fast path for numeric values: Numbers and numeric strings skip regex parsing
Regex optimization: The time unit regex is compiled once and reused
Input validation: Early returns for invalid inputs to avoid unnecessary processing
String length limit: Input strings longer than 100 characters are rejected to prevent DoS attacks

Use Cases

1. Configuration Parsing

// Parse configuration from environment variables
const config = {
  timeout: parseMSec(process.env.REQUEST_TIMEOUT || '30s'),
  interval: parseMSec(process.env.POLL_INTERVAL || '5m', true),
  ttl: parseMSec(process.env.CACHE_TTL || '24h')
};

2. CLI Argument Processing

import { Command } from 'commander';

const program = new Command();

program
  .option('-t, --timeout <duration>', 'Timeout duration', '30s')
  .option('-i, --interval <duration>', 'Poll interval', '1m')
  .action((options) => {
    const timeoutMs = parseMSec(options.timeout);
    const intervalSec = parseMSec(options.interval, true);
    
    // Use the parsed values
    startService({ timeoutMs, intervalSec });
  });

3. API Response Handling

interface ApiResponse {
  data: any;
  retryAfter: string; // e.g., "5m", "30s", "2h"
}

function handleRateLimit(response: ApiResponse) {
  const retryDelay = parseMSec(response.retryAfter);
  if (!isNaN(retryDelay)) {
    scheduleRetry(retryDelay);
  }
}

4. Duration Calculations

function calculateTotalDuration(tasks: Array<{ duration: string }>): number {
  return tasks.reduce((total, task) => {
    const ms = parseMSec(task.duration);
    return total + (isNaN(ms) ? 0 : ms);
  }, 0);
}

const tasks = [
  { name: 'Task A', duration: '30m' },
  { name: 'Task B', duration: '2h' },
  { name: 'Task C', duration: '45m' }
];

const totalMs = calculateTotalDuration(tasks);
console.log(`Total duration: ${totalMs}ms (${parseMSec(totalMs, true)}s)`);

Integration Examples

With Express.js

import express from 'express';
import { parseMSec } from "toolbox-x/utils";

const app = express();

app.use((req, res, next) => {
  // Parse cache-control header
  const cacheControl = req.headers['cache-control'];
  if (cacheControl?.includes('max-age=')) {
    const maxAge = cacheControl.match(/max-age=(\d+)/)?.[1];
    if (maxAge) {
      res.locals.cacheDuration = parseMSec(`${maxAge}s`);
    }
  }
  next();
});

With Job Scheduling

import { parseMSec } from "toolbox-x/utils";
import { scheduleJob } from 'node-schedule';

function scheduleRecurringJob(name: string, interval: string, task: () => void) {
  const intervalMs = parseMSec(interval);
  if (isNaN(intervalMs)) {
    throw new Error(`Invalid interval for job ${name}: ${interval}`);
  }
  
  setInterval(task, intervalMs);
  console.log(`Scheduled job "${name}" to run every ${interval}`);
}

scheduleRecurringJob('cleanup', '1d', cleanupOldData);
scheduleRecurringJob('backup', '6h', backupDatabase);

Alias

parseMSec can also be imported using alias:

parseMs

Note

This function is designed for parsing time into ms/sec, not absolute timestamps. For date/time parsing and manipulation, consider using Chronos class or other date utilities.