ngx-timeago-shortnum

Angular v20 standalone pipes for:

• Relative time: “2 minutes ago / in 5 hours” (auto-refreshing)
• Compact numbers: 1k · 2m · 3b and Arabic forms: ألف · مليون · مليار

Treeshakable, SSR-aware, zero dependencies.

Table of contents

• Features
• Install
• Quick start
• Usage
  • timeAgo pipe
  • shortNumber pipe
• Global configuration
• Internationalization (Arabic)
• SSR & performance notes
• Compatibility
• Troubleshooting
• Examples
• Contributing
• License
• ملخص عربي

Features

• ✅ Angular v20 standalone pipes (no NgModule required)
• ⏱️ Auto-refreshing time-ago with smart intervals
• 🌍 i18n-friendly via Intl.RelativeTimeFormat + Arabic words/digits support
• 🔤 Configurable styles: 'long' | 'short' | 'narrow' for time; 'latin' | 'arabic' | 'auto' for numbers
• 🧠 SSR-safe: timers skipped server-side; graceful text fallback
• 🧩 Zero runtime deps; treeshakable; ESM

Install

npm i ngx-timeago-shortnum

Angular 20+ is required (see Compatibility).

Quick start

If you want Arabic digits/formatting, register the Arabic locale once (optional):

// main.ts
import { bootstrapApplication, LOCALE_ID } from '@angular/core';
import { registerLocaleData } from '@angular/common';
import ar from '@angular/common/locales/ar';

registerLocaleData(ar);

bootstrapApplication(AppComponent, {
  providers: [{ provide: LOCALE_ID, useValue: 'ar' }]
});

Import the pipes directly in any standalone component:

import { Component } from '@angular/core';
import { TimeAgoPipe, ShortNumberPipe } from 'ngx-timeago-shortnum';

@Component({
  selector: 'app-demo',
  standalone: true,
  imports: [TimeAgoPipe, ShortNumberPipe],
  template: `
    <p>Created: {{ createdAt | timeAgo }}</p>
    <p>Views:   {{ views | shortNumber:1 }}</p>
  `
})
export class DemoComponent {
  createdAt = new Date(Date.now() - 42 * 60 * 1000); // 42 minutes ago
  views = 1_234_567;
}

Usage

timeAgo pipe

Auto-refreshing relative time using Intl.RelativeTimeFormat.

Signature

timeAgo(
  value: Date | string | number,
  locale?: string,                    // default: Angular LOCALE_ID or 'en'
  numeric: 'auto' | 'always' = 'auto',
  style: 'long' | 'short' | 'narrow' = 'short'
): string

Examples

<!-- Uses LOCALE_ID -->
<span>{{ createdAt | timeAgo }}</span>

<!-- Force English, narrow style -->
<span>{{ createdAt | timeAgo:'en':'auto':'narrow' }}</span>

<!-- Works for future dates too -->
<span>{{ willStartAt | timeAgo }}</span> <!-- in 3 hours -->

Behavior

• Pipe is pure: false and auto-schedules refresh based on the current unit (seconds/minutes/hours…).
• SSR: skips timers; if Intl.RelativeTimeFormat is unavailable, a simple fallback string is used.

shortNumber pipe

Compacts numbers to k/m/b/t. With Arabic locale it can output Arabic words and digits.

Signature

shortNumber(
  value: number | string,
  decimals: number = 0,               // fraction digits for compact values
  locale?: string,                    // default: Angular LOCALE_ID or 'en'
  style: 'auto' | 'latin' | 'arabic' = 'auto',
  letterCase: 'lower' | 'upper' = 'lower' // for 'latin' style only
): string

Examples

<!-- Locale-driven (auto) -->
{{ 1234567 | shortNumber:1 }}                 <!-- "١٫٢ مليون" if LOCALE_ID='ar'; "1.2m" if 'en' -->

<!-- Latin uppercase suffix -->
{{ 9876543210 | shortNumber:2:'en':'latin':'upper' }} <!-- "9.88B" -->

<!-- Force Arabic words even with English LOCALE_ID -->
{{ 1200 | shortNumber:0:'en':'arabic' }}      <!-- "1 ألف" -->

<!-- Below 1000: normal localized formatting -->
{{ 950 | shortNumber }}                        <!-- "950" or "٩٥٠" -->

Global configuration

You can set defaults app-wide using the TIME_AGO_CONFIG token.

// app.config.ts (or main.ts providers)
import { TIME_AGO_CONFIG } from 'ngx-timeago-shortnum';

export const appConfig = {
  providers: [
    {
      provide: TIME_AGO_CONFIG,
      useValue: {
        defaultLocale: 'ar',           // fallback if LOCALE_ID not provided
        rtfStyle: 'short',             // 'long' | 'short' | 'narrow'
        secondResolution: 1            // refresh cadence while in "seconds"
      }
    }
  ]
};

Internationalization (Arabic)

• If your LOCALE_ID starts with 'ar' and you’ve called registerLocaleData(ar), the package:
  • Uses Arabic digits for numbers.
  • Defaults shortNumber style to Arabic words: ألف, مليون, مليار, تريليون.
• Override anytime:
  • Latin suffixes: | shortNumber:1:'en':'latin'
  • Arabic words regardless of locale: | shortNumber:1:'en':'arabic'
• timeAgo respects locale and style (try 'narrow' for compact UI: “قبل دقيقة / خلال دقيقة”).

SSR & performance notes

• SSR safety: The timeAgo pipe skips timers on the server. On the client it reschedules minimal updates (e.g., every second for recent times, then less often).
• Change detection: The pipe runs updates outside Angular zone and calls markForCheck() for efficient re-rendering.
• Best practices
  • Prefer OnPush components.
  • Bind stable Date instances (don’t recreate new Date() on each CD cycle).
  • Avoid piping extremely large lists of timestamps in the same view; consider virtual scroll.

Compatibility

• Angular: v20+
• TypeScript: 5.x+
• Runtime: Modern browsers / Node with Intl.RelativeTimeFormat. A text fallback is used if Intl.RelativeTimeFormat is missing.

Troubleshooting

• Arabic digits aren’t shown
  • Ensure registerLocaleData(ar) is called before bootstrapping, and optionally set LOCALE_ID: 'ar'.
• Pipe doesn’t seem to refresh
  • Auto-refresh only runs in the browser. Check that you’re not viewing server-rendered HTML without client hydration.
• “Intl.RelativeTimeFormat is undefined”
  • Very old environments: consider a polyfill, or rely on the built-in string fallback.

Examples

<!-- Title attribute for exact timestamp, content shows relative time -->
<time [attr.title]="createdAt | date:'medium'">
  {{ createdAt | timeAgo:'ar':'auto':'narrow' }}
</time>

<!-- Mixed languages on one page -->
<div>
  <span class="en">{{ createdAt | timeAgo:'en' }}</span>
  <span class="ar">{{ createdAt | timeAgo:'ar' }}</span>
</div>

<!-- Dashboard cards -->
<div class="metric">
  {{ totalUsers | shortNumber:1 }} <!-- 12.3k / ١٢٫٣ ألف -->
  <small>Users</small>
</div>

Contributing

PRs and issues are welcome!
If you’re proposing a new option, please include tests and docs updates.

Local dev

# build the library
ng build ngx-timeago-shortnum

# pack & install into a demo app
cd dist/ngx-timeago-shortnum
npm pack
# in your app:
npm i ../path/to/ngx-timeago-shortnum-*.tgz

License

MIT

ملخص عربي (Quick Start)

• ثبّت الحزمة: npm i ngx-timeago-shortnum
• (اختياري) فعّل العربية:

  registerLocaleData(ar);
  providers: [{ provide: LOCALE_ID, useValue: 'ar' }];

• أمثلة:

  {{ createdAt | timeAgo }}        <!-- قبل ٣ دقائق / خلال ٥ دقائق -->
  {{ 1500 | shortNumber }}         <!-- ١ ألف -->
  {{ 1234567 | shortNumber:1 }}    <!-- ١٫٢ مليون -->