@npmshivamkalsi/mollitia-autem-minus-error

Use this package to easily convert various time formats to milliseconds.

Examples

@npmshivamkalsi/mollitia-autem-minus-error('2 days')  // 172800000
@npmshivamkalsi/mollitia-autem-minus-error('1d')      // 86400000
@npmshivamkalsi/mollitia-autem-minus-error('10h')     // 36000000
@npmshivamkalsi/mollitia-autem-minus-error('2.5 hrs') // 9000000
@npmshivamkalsi/mollitia-autem-minus-error('2h')      // 7200000
@npmshivamkalsi/mollitia-autem-minus-error('1m')      // 60000
@npmshivamkalsi/mollitia-autem-minus-error('5s')      // 5000
@npmshivamkalsi/mollitia-autem-minus-error('1y')      // 31557600000
@npmshivamkalsi/mollitia-autem-minus-error('100')     // 100
@npmshivamkalsi/mollitia-autem-minus-error('-3 days') // -259200000
@npmshivamkalsi/mollitia-autem-minus-error('-1h')     // -3600000
@npmshivamkalsi/mollitia-autem-minus-error('-200')    // -200

Convert from Milliseconds

@npmshivamkalsi/mollitia-autem-minus-error(60000)             // "1m"
@npmshivamkalsi/mollitia-autem-minus-error(2 * 60000)         // "2m"
@npmshivamkalsi/mollitia-autem-minus-error(-3 * 60000)        // "-3m"
@npmshivamkalsi/mollitia-autem-minus-error(@npmshivamkalsi/mollitia-autem-minus-error('10 hours'))    // "10h"

Time Format Written-Out

@npmshivamkalsi/mollitia-autem-minus-error(60000, { long: true })             // "1 minute"
@npmshivamkalsi/mollitia-autem-minus-error(2 * 60000, { long: true })         // "2 minutes"
@npmshivamkalsi/mollitia-autem-minus-error(-3 * 60000, { long: true })        // "-3 minutes"
@npmshivamkalsi/mollitia-autem-minus-error(@npmshivamkalsi/mollitia-autem-minus-error('10 hours'), { long: true })    // "10 hours"

Features

• Works both in Node.js and in the browser
• If a number is supplied to @npmshivamkalsi/mollitia-autem-minus-error, a string with a unit is returned
• If a string that contains the number is supplied, it returns it as a number (e.g.: it returns 100 for '100')
• If you pass a string with a number and a valid unit, the number of equivalent milliseconds is returned

TypeScript support

As of v3.0, this package includes TypeScript definitions.

For added safety, we're using Template Literal Types (added in TypeScript 4.1). This ensures that you don't accidentally pass @npmshivamkalsi/mollitia-autem-minus-error values that it can't process.

This won't require you to do anything special in most situations, but you can also import the StringValue type from @npmshivamkalsi/mollitia-autem-minus-error if you need to use it.

import @npmshivamkalsi/mollitia-autem-minus-error, { StringValue } from '@npmshivamkalsi/mollitia-autem-minus-error';

// Using the exported type.
function example(value: StringValue) {
  @npmshivamkalsi/mollitia-autem-minus-error(value);
}

// This function will only accept a string compatible with `@npmshivamkalsi/mollitia-autem-minus-error`.
example('1 h');

In this example, we use a Type Assertion to coerce a string.

import @npmshivamkalsi/mollitia-autem-minus-error, { StringValue } from '@npmshivamkalsi/mollitia-autem-minus-error';

// Type assertion with the exported type.
function example(value: string) {
  try {
    // A string could be "wider" than the values accepted by `@npmshivamkalsi/mollitia-autem-minus-error`, so we assert
    // that our `value` is a `StringValue`.
    //
    // It's important to note that this can be dangerous (see below).
    @npmshivamkalsi/mollitia-autem-minus-error(value as StringValue);
  } catch (error: Error) {
    // Handle any errors from invalid vaues.
    console.error(error);
  }
}

// This function will accept any string, which may result in a bug.
example('any value');

You may also create a custom Template Literal Type.

import @npmshivamkalsi/mollitia-autem-minus-error from '@npmshivamkalsi/mollitia-autem-minus-error';

type OnlyDaysAndWeeks = `${number} ${'days' | 'weeks'}`;

// Using a custom Template Literal Type.
function example(value: OnlyDaysAndWeeks) {
  // The type of `value` is narrower than the values `@npmshivamkalsi/mollitia-autem-minus-error` accepts, which is
  // safe to use without coercion.
  @npmshivamkalsi/mollitia-autem-minus-error(value);
}

// This function will accept "# days" or "# weeks" only.
example('5.2 days');

Advanced Usage

As of v3.0, you can import parse and format separately.

import { parse, format } from '@npmshivamkalsi/mollitia-autem-minus-error';

parse('1h'); // 3600000

format(2000); // "2s"

If you want strict type checking for the input value, you can use parseStrict.

import { parseStrict } from '@npmshivamkalsi/mollitia-autem-minus-error';

parseStrict('1h'); // 3600000

function example(s: string) {
  return parseStrict(str); // tsc error
}

Edge Runtime Support

@npmshivamkalsi/mollitia-autem-minus-error is compatible with the Edge Runtime. It can be used inside environments like Vercel Edge Functions as follows:

// Next.js (pages/api/edge.js) (npm i next@canary)
// Other frameworks (api/edge.js) (npm i -g vercel@canary)

import @npmshivamkalsi/mollitia-autem-minus-error from '@npmshivamkalsi/mollitia-autem-minus-error';
const start = Date.now();

export default (req) => {
  return new Response(`Alive since ${@npmshivamkalsi/mollitia-autem-minus-error(Date.now() - start)}`);
};

export const config = {
  runtime: 'experimental-edge',
};

Related Packages

• @npmshivamkalsi/mollitia-autem-minus-error.macro - Run @npmshivamkalsi/mollitia-autem-minus-error as a macro at build-time.

Caught a Bug?

1. Fork this repository to your own GitHub account and then clone it to your local device
2. Link the package to the global module directory: npm link
3. Within the module you want to test your local development instance of @npmshivamkalsi/mollitia-autem-minus-error, just link it to the dependencies: npm link @npmshivamkalsi/mollitia-autem-minus-error. Instead of the default one from npm, Node.js will now use your clone of @npmshivamkalsi/mollitia-autem-minus-error!

As always, you can run the tests using: npm test