{"_id":"@ashetm/ng-network","name":"@ashetm/ng-network","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ashetm/ng-network","version":"1.0.0","contributors":[{"name":"DAWOUD Haitham","email":"contact@ashetm.com","url":"http://ashetm.com"}],"author":{"name":"DAWOUD Haitham","email":"contact@ashetm.com","url":"http://ashetm.com"},"keywords":["angular","directive","internet","js","network","ng","ng-directive","ng-service","ng-services","ng-network","observable","observables","offline","online","operators","rxjs","rxjs/operators","ts"],"private":false,"repository":{"url":"git+https://github.com/AsheTM/ng-services.git#develop"},"peerDependencies":{"@angular/common":">=16.0.0","@angular/core":">=16.0.0","rxjs":">=6.6.0"},"dependencies":{"tslib":"^2.3.0"},"sideEffects":false,"module":"fesm2022/ashetm-ng-network.mjs","typings":"index.d.ts","exports":{"./package.json":{"default":"./package.json"},".":{"types":"./index.d.ts","esm2022":"./esm2022/ashetm-ng-network.mjs","esm":"./esm2022/ashetm-ng-network.mjs","default":"./fesm2022/ashetm-ng-network.mjs"}},"_id":"@ashetm/ng-network@1.0.0","gitHead":"bd63e16791a7bf115b522311fbdd0a023be4d248","description":"``@ashetm/ng-network`` is a library that provide some utilities classes, like pipes.","bugs":{"url":"https://github.com/AsheTM/ng-services/issues"},"homepage":"https://github.com/AsheTM/ng-services/tree/develop#readme","_nodeVersion":"20.11.1","_npmVersion":"10.2.4","dist":{"integrity":"sha512-/943W6fbzN4q2cWN9B6tnIIr58WPDdLsGFIW1Ntm6J6O0dk5a3w9MaEsxgJ6W6KkIXxjQ4S04gSmfpzxg8+bjw==","shasum":"a17fde19cd329f1fbc5eeba9c4861eb1b69200ad","tarball":"https://registry.npmjs.org/@ashetm/ng-network/-/ng-network-1.0.0.tgz","fileCount":17,"unpackedSize":42561,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDqNrOOztBbe8fYXmZKRyO44NY/ORVWrJPUk74D/vB48AIgM3LrxaX/Vbe1B85Gct7+aR0hS0RFE1rcSiWir+SNoQM="}]},"_npmUser":{"name":"ashetm","email":"haithemalidaoud@gmail.com"},"directories":{},"maintainers":[{"name":"ashetm","email":"haithemalidaoud@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ng-network_1.0.0_1736863198149_0.6796907219246933"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-14T13:59:58.011Z","1.0.0":"2025-01-14T13:59:58.330Z","modified":"2025-01-14T13:59:58.595Z"},"maintainers":[{"name":"ashetm","email":"haithemalidaoud@gmail.com"}],"description":"``@ashetm/ng-network`` is a library that provide some utilities classes, like pipes.","homepage":"https://github.com/AsheTM/ng-services/tree/develop#readme","keywords":["angular","directive","internet","js","network","ng","ng-directive","ng-service","ng-services","ng-network","observable","observables","offline","online","operators","rxjs","rxjs/operators","ts"],"repository":{"url":"git+https://github.com/AsheTM/ng-services.git#develop"},"contributors":[{"name":"DAWOUD Haitham","email":"contact@ashetm.com","url":"http://ashetm.com"}],"author":{"name":"DAWOUD Haitham","email":"contact@ashetm.com","url":"http://ashetm.com"},"bugs":{"url":"https://github.com/AsheTM/ng-services/issues"},"readme":"\n# @ashetm/ng-network\n\n``@ashetm/ng-network`` is a library that provide some utilities classes, like pipes.\n\n<!-- [![build status](http://img.shields.io/travis/likeastore/ngDialog.svg)](https://travis-ci.org/likeastore/ngDialog) -->\n<!-- [![npm version](http://badge.fury.io/js/ng-dialog.svg)](http://badge.fury.io/js/ng-dialog) -->\n<!-- [![github tag](https://img.shields.io/github/tag/likeastore/ngDialog.svg)](https://github.com/likeastore/ngDialog/tags) -->\n<!-- [![Download Count](https://img.shields.io/npm/dm/ng-dialog.svg)](http://www.npmjs.com/package/ng-dialog) -->\n<!-- [![Code Climate](https://codeclimate.com/github/likeastore/ngDialog/badges/gpa.svg)](https://codeclimate.com/github/likeastore/ngDialog) -->\n\n<!-- ### [Demo](http://likeastore.github.io/ngDialog) -->\n\n## Compatibility Table\n\n| Angular Version    | @ashetm/ng-network Version     | RxJS Version   | Support |\n|--------------------|--------------------------------|----------------|---------|\n| Angular 16.x and + | @ashetm/ng-network 16.x and +  | 6.x.x and +    | ✅      |\n\n## Install\n\nYou can install it with npm:\n\n```bash\nnpm install @ashetm/ng-network\n```\n\n## API\n\n``@ashetm/ng-network`` exposes the following: \n\n### Directives\n\n#### NetworkDirective\n\n* _Selector_: `ashetmNetwork`\n\nThis Angular **standalone** **structural** directive listens for changes in the network connection status and provides observable data about the network's current state and the last time it was connected. It uses fromNetworkEvents to detect online/offline status and fromNetworkLastTimeConnected to track the last time the device was connected.\n\n**Usage Example:**\n\nImporting the specific standalone ``NetworkDirective`` step is required.\n\n```html\n<ng-template ashetmNetwork let-network let-lastTimeConnected$=\"lastTimeConnected$\">\n  <div *ngIf=\"network | async\">You are online</div>\n  <div *ngIf=\"!(network | async)\">You are offline</div>\n  <div *ngIf=\"lastTimeConnected$ | async as lastConnected\">Last connected: {{ lastConnected }} ms ago</div>\n</ng-template>\n```\n\n**Explanation:**\n\n* _network_: This observable emits a boolean value, `true` if the device is online and `false` if the device is offline.\n* _lastTimeConnected$_: This observable emits the last time the device was connected in milliseconds. It emits undefined when the device is online.\n\n### Custom RXJS Observables\n\n#### `fromOfflineEvent()`\n\n```ts\nfunction fromOfflineEvent(): Observable<void> { ... }\n```\n\nEmits a notification when the device goes offline.\n\nReturns:\n\nAn observable emitting a void.\n\nExample: \n\n```tsx\nfromOfflineEvent().subscribe(() => {\n  console.log('Device is offline');\n});\n```\n\n#### `fromOnlineEvent()`\n\n```ts\nfunction fromOnlineEvent(): Observable<void> { ... }\n```\n\nEmits a notification when the device goes online.\n\n**Example:**\n\n```tsx\nfromOnlineEvent().subscribe(() => {\n  console.log('Device is online');\n});\n```\n\n#### `fromNetworkEvents()`\n\n```ts\nfunction fromNetworkEvents(): Observable<boolean> { ... }\n```\n\nEmits true when the device is online and false when the device is offline.\n\n**Example:**\n\n```tsx\nfromNetworkEvents().subscribe((isOnline: boolean) => {\n  console.log(`Network status: ${isOnline ? 'Online' : 'Offline'}`);\n});\n```\n\n#### `fromNetworkLastTimeConnected()`\n\n```ts\nfunction fromNetworkLastTimeConnected(): Observable<number | undefined> { ... }\n```\n\nEmits the last time the device was connected (in milliseconds) or undefined if the device is currently online.\n\n**Example:**\n\n```tsx\nfromNetworkLastTimeConnected().subscribe((lastConnected: number | undefined) => {\n  if(typeof lastConnected === 'number')\n    console.log(`Last connected: ${lastConnected} ms ago`);\n  else\n    console.log(`Last connected: is currently connected`);\n});\n```\n\n#### `fromNetworkStatus()`\n\n```ts\nfunction fromNetworkStatus(): Observable<NetworkStatus | undefined> { ... }\n```\n\nThis observable provides detailed network status information, including the connection type, downlink speed, round-trip time, and whether data saver mode is enabled. The observable emits updates whenever the network conditions change.\n\n**Parameters:**\n\n* _online_: Indicates whether the device is online (true or false).\n* _type_: The type of network connection (e.g., wifi, cellular).\n* _downlink_: The estimated downlink speed in Mbps.\n* _rtt_: The estimated round-trip time in milliseconds.\n* _saveData_: Indicates whether the user has enabled data saver mode.\n\n**Example:**\n\n```tsx\nfromNetworkStatus().subscribe((status: NetworkStatus) => {\n  console.log(`Online: ${status.online}`);\n  console.log(`Connection Type: ${status.type}`);\n  console.log(`Downlink: ${status.downlink} Mbps`);\n  console.log(`RTT: ${status.rtt} ms`);\n  console.log(`Data Saver Enabled: ${status.saveData}`);\n});\n```\n\n### Custom RXJS Operators\n\n#### `retryUntilOnline()`\n\n```ts\nfunction retryUntilOnline<T>(durationStep: number = 1000, timeIncreasing: boolean = false): MonoTypeOperatorFunction<T>  { ... }\n```\n\nThe ``retryUntilOnline`` operator is **an experimental feature** that automatically retries an observable operation whenever it fails. If the network is offline, it retries the operation with an increasing delay until the network becomes online again. Once the network is online, the operation retries immediately.\n\n**Parameters:**\n\n* `durationStep`: The base delay time in milliseconds (default is `1000 ms`).\n* `timeIncreasing`: A boolean that determines whether the retry delay should increase with each attempt (default is `false`).\n\n**Example:**\n\n```tsx\nimport { ajax } from 'rxjs/ajax';\nimport { catchError, tap, of } from 'rxjs';\n\nimport { retryUntilOnline } from '@ashetm//ng-network';\n\n// Mock API endpoint\nconst apiEndpoint = 'https://jsonplaceholder.typicode.com/posts/1';\n\n// Simulated HTTP request\nconst httpRequest$ = ajax.getJSON(apiEndpoint).pipe(\n  tap((response) => console.log('Request successful:', response)),\n  catchError((error) => {\n    console.error('Request failed:', error);\n    return of(null); // Handle the error and emit a fallback value\n  }),\n  retryUntilOnline(1000) // Retry every 1 second until the network is online\n);\n\n// Subscribe to the observable\nhttpRequest$.subscribe({\n  next: (data) => console.log('Final data:', data),\n  error: (err) => console.error('Subscription error:', err),\n  complete: () => console.log('Request completed'),\n});\n\n```\n\n### Types\n\n#### `NetworkStatus`\n\nThe `NetworkStatus` interface defines the structure of the network status object emitted by the `fromNetworkStatus()` observable.\n\n**Parameters:**\n\n* `effectiveType`: A string representing the effective network connection type (e.g., 4g, 3g, 2g, or slow-2g).\n* `downlink`: The approximate bandwidth of the connection in megabits per second.\n* `rtt`: The estimated round-trip time for requests in milliseconds.\n* `saveData`: A boolean indicating whether the user has enabled the browser's data-saver mode.\n\n## Issue\n\nLOOKING FOR MAINTAINER OR IF THERE IS AN ISSUE OR ANY IDEA TO ADD. PLEASE CREATE ISSUE IN GITHUB REPOSITORY.\n","readmeFilename":"README.md"}