time-diff-describer

A class used to describe time differences in human language, like "3 days ago", "1 week ago" or "2 years later".

Install

Run following command in the root directory of your project:

npm install @pangbolabs/time-diff-describer -S

API

Constructor

Create a TimeDiffDescriber instance.

TimeDiffDescriber( stringTable = null )

Parameters

• stringTable: An object contains the strings to be used when describing the time difference. Set it to null to use the default string table. The default string table contains strings for English description.

Refer to the section for setStringTable() for detailed information about the string table.

describeTimeDiff

Describe the difference between the specified time and a base time.

describer.describeTimeDiff( time, baseTime = new Date() )

Parameters

• time
• baseTime

Returns

The string which describes the difference between time and baseTime.

setStringTable

Set the strings to be used when describing the time difference.

describer.setStringTable( stringTable )

Parameters

• stringTable: An object contains the strings to be used when describing the time difference. Set it to null to use the default string table. The default string table contains strings for English description.

The default string table is:

{
    format: "{count} {unit} {relation}",
    relations:
    {
        ago:    "ago",
        later:  "later",
        now:    "Now",
    },
    units:
    {
        millisecond:    { singular: "millisecond",  plural: "milliseconds"  },
        second:         { singular: "second",       plural: "seconds"       },
        minitue:        { singular: "minitue",      plural: "minitues"      },
        hour:           { singular: "hour",         plural: "hours"         },
        day:            { singular: "day",          plural: "days"          },
        week:           { singular: "week",         plural: "weeks"         },
        month:          { singular: "month",        plural: "months"        },
        year:           { singular: "year",         plural: "years"         },
    }
};

Returns

This method will not return any value.

Examples

import { TimeDiffDescriber } from '@pangbolabs/time-diff-describer'

let describer = new TimeDiffDescriber();

let now = new Date();
let str;

// describe the difference between the specified time and the current time
str = describer.describeTimeDiff( new Date( '2024/11/25 16:49:00' ), now );
console.log( str );

// describe the difference between the specified time and the current time through the default parameter
str = describer.describeTimeDiff( new Date( '2024/11/25 16:49:00' ) );
console.log( str );

// specify own string table for formatting the description
describer.setStringTable( {
    format: "{count} {unit}{relation}",
    relations:
    {
        ago:    "前",
        later:  "后",
        now:    "现在",
    },
    units:
    {
        millisecond:    { singular: "毫秒",    plural: "毫秒"   },
        second:         { singular: "秒",      plural: "秒"    },
        minitue:        { singular: "分钟",    plural: "分钟"   },
        hour:           { singular: "小时",    plural: "小时"   },
        day:            { singular: "天",      plural: "天"    },
        week:           { singular: "周",      plural: "周"    },
        month:          { singular: "月",      plural: "月"    },
        year:           { singular: "年",      plural: "年"    },
    }
} );

// describe the difference using the specified string table
str = describer.describeTimeDiff( new Date( '2024/11/25 16:49:00' ) );
console.log( str );

// set to use the default string table
describer.setStringTable( null );

// describe the difference using the default string table
str = describer.describeTimeDiff( new Date( '2024/11/25 16:49:00' ), new Date( '2025/11/28' ) );
console.log( str );

// describe the difference between the specified time and a later time
str = describer.describeTimeDiff( new Date( '2024/11/25 16:49:00' ), new Date( '2021/11/02' ) );
console.log( str );

The output of above will be:

1 day ago
1 day ago
1 天前
1 year ago
3 years later

Make localized descriptions, for example use together with the vue-i18n:

import { TimeDiffDescriber } from '@pangbolabs/time-diff-describer'

let describer = new TimeDiffDescriber( {
    format: this.$t( "timeDiffDescFormat" ),
    relations:
    {
        ago:    this.$t( "ago" ),
        later:  this.$t( "later" ),
        now:    this.$t( "now" ),
    },
    units:
    {
        millisecond:    { singular: this.$t( "millisecond" ),    plural: this.$t( "milliseconds" )   },
        second:         { singular: this.$t( "second" ),         plural: this.$t( "seconds" )        },
        minitue:        { singular: this.$t( "minute" ),         plural: this.$t( "minutes" )        },
        hour:           { singular: this.$t( "hour" ),           plural: this.$t( "hours" )          },
        day:            { singular: this.$t( "day" ),            plural: this.$t( "days" )           },
        week:           { singular: this.$t( "week" ),           plural: this.$t( "weeks" )          },
        month:          { singular: this.$t( "month" ),          plural: this.$t( "months" )         },
        year:           { singular: this.$t( "year" ),           plural: this.$t( "years" )          },
    }
} );

str = describer.describeTimeDiff( new Date( '2024/11/25 16:49:00' ) );
console.log( str );

The # Character Problem

When using this module with some framework, such as Vue and React, you may got an error saying "Unexpected character '#'" or the class private member feature was not enabled. That is because those frameworks don't process ES6 feature by default. You need to configure Babel to process the package. Following are the steps.

1. Configure the webpack

For example, in a Vue project, open the vue.config.js. If you cannot find it in the root folder of the project, create one. Then add a module rule to let babel-loader to process the .js or .mjs files in the package. Following is an sample vue.config.js:

const path = require( 'path' )

module.exports = {
    configureWebpack: {
        module: {
            rules: [
                {
                    test: /\.m?js$/,
                    // include: /node_modules[/\\|]@pangbolabs[/\\|]time-diff-describer/,
                    include: path.resolve( __dirname, './node_modules/@pangbolabs/time-diff-describer' ),
                    use: {
                        loader: 'babel-loader'
                    }
                }
            ]
        }
    }
}

The above sample contains two ways to write the include field (one was commented out). You can choose one of them according to your preference.

If you already have the vue.config.js, add above rule to your file.

2. Restart the project

Although the running project will detect the change of the vue.config.js, it's better to restart your project.

If you're using other frameworks, you can make similar webpack configuration.

License

Mozilla

Copyright

Copyright (C) Pangbo Labs, 2024.