Package Exports

ngx-timeago-shortnum
ngx-timeago-shortnum/package.json

Readme

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.

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 }}    <!-- ١٫٢ مليون -->

JSPM