@su-labs/visit-tracker 22.0.0 → 22.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -0
- package/README.md +59 -41
- package/fesm2022/su-labs-visit-tracker.mjs +10 -19
- package/fesm2022/su-labs-visit-tracker.mjs.map +1 -1
- package/package.json +3 -2
- package/types/su-labs-visit-tracker.d.ts +23 -27
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [22.1.1] - 2026-11-14
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
- Package homepage now points to the website with a live demo
|
|
12
|
+
- Pins `@su-labs/core` to exactly 1.8.0
|
|
13
|
+
|
|
14
|
+
## [22.1.0] - 2026-11-05
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
- Visit tracking moved to the framework-agnostic `@su-labs/core/visit-tracker`; `SuVisitTrackerService` is now a thin wrapper with the same API
|
|
18
|
+
- `SuVisitTrackerConfig` and `SuVisitData` are now re-exported from `@su-labs/core/visit-tracker`
|
|
19
|
+
- Added `@su-labs/core` as a dependency
|
|
20
|
+
- README links to the `@su-labs/core` installation guides for non-Angular projects
|
|
21
|
+
|
|
22
|
+
### Fixed
|
|
23
|
+
- Corrupted or invalid saved data no longer throws; counting starts over
|
|
24
|
+
- `init()` no longer sorts the `milestoneVisits` array passed in the config
|
|
25
|
+
- Safe to call during server-side rendering (no `localStorage` access without a browser)
|
|
26
|
+
- README now documents the actual API (`milestone()` signal, `init()` required)
|
|
27
|
+
- Repair table of contents links in README.md
|
|
28
|
+
|
|
8
29
|
## [22.0.0] - 2026-11-04
|
|
9
30
|
|
|
10
31
|
### Changed
|
package/README.md
CHANGED
|
@@ -13,28 +13,30 @@
|
|
|
13
13
|
|
|
14
14
|
A lightweight Angular service to track user visits. Provides reactive signals for visit count, last visit date, and milestone visits.
|
|
15
15
|
|
|
16
|
+
> **Not using Angular?** The same visit tracker is available for React, Vue, Svelte and vanilla JavaScript in [`@su-labs/core`](https://www.npmjs.com/package/@su-labs/core). See the [installation guides](https://github.com/Greezaaa/settings-utils-lib/blob/main/docs/README.md).
|
|
17
|
+
|
|
16
18
|
## Table of Contents
|
|
17
19
|
|
|
18
|
-
- [Why Use This Library?](
|
|
20
|
+
- [Why Use This Library?](#why-use-this-library)
|
|
19
21
|
- [Features](#features)
|
|
20
22
|
- [Installation](#installation)
|
|
21
|
-
- [Quick Start](
|
|
23
|
+
- [Quick Start](#quick-start)
|
|
22
24
|
- [Usage](#usage)
|
|
23
|
-
- [API Reference](
|
|
25
|
+
- [API Reference](#api-reference)
|
|
24
26
|
- [Configuration Options](#configuration-options)
|
|
25
|
-
- [Browser Compatibility](
|
|
26
|
-
- [Related Libraries](
|
|
27
|
-
- [Troubleshooting](
|
|
28
|
-
- [Support](
|
|
27
|
+
- [Browser Compatibility](#browser-compatibility)
|
|
28
|
+
- [Related Libraries](#related-libraries)
|
|
29
|
+
- [Troubleshooting](#troubleshooting)
|
|
30
|
+
- [Support](#support)
|
|
29
31
|
- [Contributing](#contributing)
|
|
30
32
|
- [License](#license)
|
|
31
33
|
|
|
32
34
|
## Why Use This Library?
|
|
33
35
|
|
|
34
|
-
- **Lightweight** -
|
|
36
|
+
- **Lightweight** - Minimal bundle size
|
|
35
37
|
- **Reactive** - Built with Angular Signals
|
|
36
38
|
- **Type-Safe** - Full TypeScript support
|
|
37
|
-
- **
|
|
39
|
+
- **SSR Safe** - No browser APIs are touched on the server
|
|
38
40
|
- **Well Tested** - Comprehensive test coverage
|
|
39
41
|
- **Well Documented** - Clear examples and API docs
|
|
40
42
|
|
|
@@ -42,7 +44,7 @@ A lightweight Angular service to track user visits. Provides reactive signals fo
|
|
|
42
44
|
|
|
43
45
|
* Tracks number of visits per user.
|
|
44
46
|
* Persists visit data in `localStorage`.
|
|
45
|
-
*
|
|
47
|
+
* Milestone signal (e.g., 10th, 100th visit).
|
|
46
48
|
* Reactive last visit date signal.
|
|
47
49
|
* Configurable storage key and milestones.
|
|
48
50
|
* Works seamlessly with standalone components and reactive Angular setups.
|
|
@@ -65,43 +67,55 @@ npm install @angular/common@^22 @angular/core@^22
|
|
|
65
67
|
|
|
66
68
|
## Quick Start
|
|
67
69
|
|
|
70
|
+
1. Record the visit once at startup in `app.config.ts`:
|
|
71
|
+
|
|
68
72
|
```typescript
|
|
69
|
-
|
|
70
|
-
|
|
73
|
+
import { ApplicationConfig, inject, provideAppInitializer } from '@angular/core';
|
|
74
|
+
import { SuVisitTrackerService } from '@su-labs/visit-tracker';
|
|
71
75
|
|
|
72
|
-
|
|
76
|
+
export const appConfig: ApplicationConfig = {
|
|
77
|
+
providers: [
|
|
78
|
+
provideAppInitializer(() => {
|
|
79
|
+
inject(SuVisitTrackerService).init();
|
|
80
|
+
}),
|
|
81
|
+
],
|
|
82
|
+
};
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
2. Read the signals in any component:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
73
88
|
import { Component, inject } from '@angular/core';
|
|
74
89
|
import { SuVisitTrackerService } from '@su-labs/visit-tracker';
|
|
75
90
|
|
|
76
91
|
@Component({
|
|
77
92
|
selector: 'app-root',
|
|
78
|
-
template: `<p>Visits: {{ visitService.count() }}</p
|
|
93
|
+
template: `<p>Visits: {{ visitService.count() }}</p>`,
|
|
79
94
|
})
|
|
80
95
|
export class AppComponent {
|
|
81
|
-
visitService = inject(SuVisitTrackerService);
|
|
96
|
+
protected readonly visitService = inject(SuVisitTrackerService);
|
|
82
97
|
}
|
|
83
98
|
```
|
|
84
99
|
|
|
85
100
|
## Usage
|
|
86
101
|
|
|
87
|
-
### Example 1:
|
|
88
|
-
|
|
102
|
+
### Example 1: Welcome back message
|
|
103
|
+
After `init()` has run (see [Quick Start](#quick-start)), inject the service wherever you need it:
|
|
89
104
|
|
|
90
105
|
```TypeScript
|
|
91
106
|
import { Component, inject } from '@angular/core';
|
|
92
|
-
import {
|
|
107
|
+
import { DatePipe } from '@angular/common';
|
|
93
108
|
import { SuVisitTrackerService } from '@su-labs/visit-tracker';
|
|
94
109
|
|
|
95
110
|
@Component({
|
|
96
111
|
selector: 'app-root',
|
|
97
|
-
|
|
98
|
-
imports: [CommonModule, DatePipe],
|
|
112
|
+
imports: [DatePipe],
|
|
99
113
|
template: `
|
|
100
114
|
<h1>Welcome back!</h1>
|
|
101
115
|
<p>You have visited {{ visitService.count() }} times.</p>
|
|
102
|
-
|
|
103
|
-
<p>Last visit: {{ last | date:'medium' }}</p>
|
|
104
|
-
|
|
116
|
+
@if (visitService.lastVisit(); as last) {
|
|
117
|
+
<p>Last visit: {{ last | date: 'medium' }}</p>
|
|
118
|
+
}
|
|
105
119
|
`,
|
|
106
120
|
})
|
|
107
121
|
export class AppComponent {
|
|
@@ -109,22 +123,23 @@ export class AppComponent {
|
|
|
109
123
|
}
|
|
110
124
|
```
|
|
111
125
|
|
|
112
|
-
|
|
126
|
+
Each `init()` call increments the visit count and saves the start of this visit for next time.
|
|
113
127
|
|
|
114
128
|
### Example 2: Checking milestone visits
|
|
115
|
-
|
|
129
|
+
`milestone()` holds the milestone reached on this visit, or `null`:
|
|
116
130
|
|
|
117
131
|
```HTML
|
|
118
|
-
@
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
@
|
|
123
|
-
|
|
132
|
+
@switch (visitService.milestone()) {
|
|
133
|
+
@case (10) {
|
|
134
|
+
<p>Congratulations on your 10th visit!</p>
|
|
135
|
+
}
|
|
136
|
+
@case (100) {
|
|
137
|
+
<p>100 visits! You're a power user!</p>
|
|
138
|
+
}
|
|
124
139
|
}
|
|
125
140
|
```
|
|
126
141
|
|
|
127
|
-
|
|
142
|
+
The signal is set when `init()` runs.
|
|
128
143
|
|
|
129
144
|
### Example 3: Custom configuration
|
|
130
145
|
For standalone apps, use provideAppInitializer to initialize the tracker with a custom storage key or milestones:
|
|
@@ -153,7 +168,7 @@ Allows overriding the localStorage key and defining custom milestone visits.
|
|
|
153
168
|
### Example 4: Using last visit date
|
|
154
169
|
|
|
155
170
|
```HTML
|
|
156
|
-
@if(visitService.lastVisit() as last) {
|
|
171
|
+
@if (visitService.lastVisit(); as last) {
|
|
157
172
|
<p>
|
|
158
173
|
Your last visit was on {{ last | date:'fullDate' }} at {{ last | date:'shortTime' }}
|
|
159
174
|
</p>
|
|
@@ -168,16 +183,15 @@ The service stores last visit as an ISO string (e.g., "2025-08-25T12:34:56.789Z"
|
|
|
168
183
|
|
|
169
184
|
| Signal | Type | Description |
|
|
170
185
|
|--------|------|-------------|
|
|
171
|
-
| `count()` | `number` |
|
|
172
|
-
| `lastVisit()` | `string \| null` | ISO string
|
|
173
|
-
| `
|
|
174
|
-
| `isHundredthVisit()` | `boolean` | True if current count is 100 |
|
|
186
|
+
| `count()` | `number` | Visit count including this visit (`0` before `init()`) |
|
|
187
|
+
| `lastVisit()` | `string \| null` | Start of the previous visit as an ISO string, or `null` on the first visit |
|
|
188
|
+
| `milestone()` | `number \| null` | Milestone reached on this visit, or `null` |
|
|
175
189
|
|
|
176
190
|
### Methods
|
|
177
191
|
|
|
178
192
|
| Method | Parameters | Description |
|
|
179
193
|
|--------|------------|-------------|
|
|
180
|
-
| `init(config?)` | `SuVisitTrackerConfig` |
|
|
194
|
+
| `init(config?)` | `SuVisitTrackerConfig` | Record the current visit. Call once at startup. |
|
|
181
195
|
|
|
182
196
|
### Types
|
|
183
197
|
|
|
@@ -226,9 +240,13 @@ Part of the **@su-labs** suite:
|
|
|
226
240
|
|
|
227
241
|
Make sure localStorage is enabled in your browser and not blocked by privacy settings.
|
|
228
242
|
|
|
229
|
-
###
|
|
243
|
+
### Count stays at 0?
|
|
244
|
+
|
|
245
|
+
The visit is only recorded when `init()` runs. Call it once at startup, as shown in [Quick Start](#quick-start).
|
|
246
|
+
|
|
247
|
+
### Milestone signal not updating?
|
|
230
248
|
|
|
231
|
-
Milestones are only checked
|
|
249
|
+
Milestones are only checked when `init()` runs, once per visit.
|
|
232
250
|
|
|
233
251
|
### TypeScript errors?
|
|
234
252
|
|
|
@@ -244,7 +262,7 @@ Ensure you have Angular 22+ and TypeScript 6.0+ installed.
|
|
|
244
262
|
|
|
245
263
|
- **Signals-based API**: Perfect for standalone components and reactive Angular templates.
|
|
246
264
|
- **Persistence**: Visit count and last visit are automatically stored in localStorage.
|
|
247
|
-
- **Lightweight**:
|
|
265
|
+
- **Lightweight**: Minimal memory footprint.
|
|
248
266
|
- **Custom milestones**: Track any number of user visit milestones reactively.
|
|
249
267
|
|
|
250
268
|
## Contributing
|
|
@@ -1,30 +1,21 @@
|
|
|
1
1
|
import * as i0 from "@angular/core";
|
|
2
2
|
import { Injectable, signal } from "@angular/core";
|
|
3
|
+
import { SuVisitTrackerController } from "@su-labs/core/visit-tracker";
|
|
3
4
|
var SuVisitTrackerService = class SuVisitTrackerService {
|
|
4
|
-
|
|
5
|
-
_milestones = [10, 100];
|
|
5
|
+
controller = new SuVisitTrackerController();
|
|
6
6
|
count = signal(0, ...ngDevMode ? [{ debugName: "count" }] : /* istanbul ignore next */ []);
|
|
7
7
|
lastVisit = signal(null, ...ngDevMode ? [{ debugName: "lastVisit" }] : /* istanbul ignore next */ []);
|
|
8
8
|
milestone = signal(null, ...ngDevMode ? [{ debugName: "milestone" }] : /* istanbul ignore next */ []);
|
|
9
|
+
unsubscribe = this.controller.visit.subscribe((visit) => {
|
|
10
|
+
this.count.set(visit.count);
|
|
11
|
+
this.lastVisit.set(visit.lastVisit);
|
|
12
|
+
this.milestone.set(visit.milestone);
|
|
13
|
+
});
|
|
9
14
|
init(config) {
|
|
10
|
-
|
|
11
|
-
if (config?.milestoneVisits && Array.isArray(config.milestoneVisits)) this._milestones = config.milestoneVisits.sort((a, b) => a - b);
|
|
12
|
-
const storedData = localStorage.getItem(this.storageKey);
|
|
13
|
-
const stored = storedData ? JSON.parse(storedData) : {};
|
|
14
|
-
const prevCount = stored.count ?? 0;
|
|
15
|
-
const prevDate = stored.lastVisit ?? null;
|
|
16
|
-
const newCount = prevCount + 1;
|
|
17
|
-
this.count.set(newCount);
|
|
18
|
-
this.lastVisit.set(prevDate);
|
|
19
|
-
this.updateMilestone(newCount);
|
|
20
|
-
localStorage.setItem(this.storageKey, JSON.stringify({
|
|
21
|
-
count: newCount,
|
|
22
|
-
lastVisit: (/* @__PURE__ */ new Date()).toISOString()
|
|
23
|
-
}));
|
|
15
|
+
this.controller.init(config);
|
|
24
16
|
}
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
this.milestone.set(reachedMilestone ?? null);
|
|
17
|
+
ngOnDestroy() {
|
|
18
|
+
this.unsubscribe();
|
|
28
19
|
}
|
|
29
20
|
static ɵfac = i0.ɵɵngDeclareFactory({
|
|
30
21
|
minVersion: "12.0.0",
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"su-labs-visit-tracker.mjs","names":[],"sources":["../../../../projects/su-labs/visit-tracker/src/lib/visit-tracker.service.ts"],"sourcesContent":["import { Injectable, signal, WritableSignal } from '@angular/core';\nimport {
|
|
1
|
+
{"version":3,"file":"su-labs-visit-tracker.mjs","names":[],"sources":["../../../../projects/su-labs/visit-tracker/src/lib/visit-tracker.service.ts"],"sourcesContent":["import { Injectable, OnDestroy, signal, WritableSignal } from '@angular/core';\nimport { SuVisitTrackerConfig, SuVisitTrackerController } from '@su-labs/core/visit-tracker';\n\n/**\n * Angular service for tracking user visits.\n *\n * Thin wrapper around the framework-agnostic `SuVisitTrackerController` from\n * `@su-labs/core/visit-tracker` that exposes the visit data as Angular signals.\n */\n@Injectable({ providedIn: 'root' })\nexport class SuVisitTrackerService implements OnDestroy {\n /** Framework-agnostic visit tracking logic */\n private readonly controller = new SuVisitTrackerController();\n\n /** Current visit count (0 until {@link init} runs) */\n public count: WritableSignal<number> = signal(0);\n\n /** Start of the previous visit as an ISO string, or null on the first visit */\n public lastVisit: WritableSignal<string | null> = signal(null);\n\n /** The number of the milestone reached on the current visit, or null */\n public milestone: WritableSignal<number | null> = signal(null);\n\n /** Stops syncing the controller's state into the signals */\n private readonly unsubscribe = this.controller.visit.subscribe((visit) => {\n this.count.set(visit.count);\n this.lastVisit.set(visit.lastVisit);\n this.milestone.set(visit.milestone);\n });\n\n /**\n * Record the current visit and update the signals.\n * Call once at application startup.\n * @param config Optional storage key and milestones.\n */\n public init(config?: SuVisitTrackerConfig): void {\n this.controller.init(config);\n }\n\n /** Angular lifecycle hook for service destruction */\n ngOnDestroy(): void {\n this.unsubscribe();\n }\n}\n"],"mappings":";;;AAUA,IAAa,wBAAb,MAAa,sBAAqB;CAEf,aAAa,IAAI,yBAAwB;CAGnD,QAAgC,OAAO,GAAE,GAAA,YAAA,CAAA,EAAA,WAAA,QAAA,CAAA,+BAAA,CAAA,CAAA;CAGzC,YAA2C,OAAO,MAAK,GAAA,YAAA,CAAA,EAAA,WAAA,YAAA,CAAA,+BAAA,CAAA,CAAA;CAGvD,YAA2C,OAAO,MAAK,GAAA,YAAA,CAAA,EAAA,WAAA,YAAA,CAAA,+BAAA,CAAA,CAAA;CAG7C,cAAc,KAAK,WAAW,MAAM,WAAW,UAAS;EACvE,KAAK,MAAM,IAAI,MAAM,KAAK;EAC1B,KAAK,UAAU,IAAI,MAAM,SAAS;EAClC,KAAK,UAAU,IAAI,MAAM,SAAS;CACpC,CAAC;CAOM,KAAK,QAA6B;EACvC,KAAK,WAAW,KAAK,MAAM;CAC7B;CAGA,cAAW;EACT,KAAK,YAAW;CAClB;CAhCW,OAAA,OAAA,GAAA,mBAAA;EAAA,YAAA;EAAA,SAAA;EAAA,UAAA;EAAA,MAAA;EAAqB,MAAA,CAAA;EAAA,QAAA,GAAA,gBAAA;CAAA,CAAA;CAArB,OAAA,QAAA,GAAA,sBAAA;EAAA,YAAA;EAAA,SAAA;EAAA,UAAA;EAAA,MAAA;EAAqB,YADR;CAAM,CAAA;;AACnB,GAAA,yBAAA;CAAA,YAAA;CAAA,SAAA;CAAA,UAAA;CAAA,MAAA;CAAqB,YAAA,CAAA;EADjC,MAAA;EAAW,MAAA,CAAA,EAAE,YAAY,OAAM,CAAE"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@su-labs/visit-tracker",
|
|
3
|
-
"version": "22.
|
|
3
|
+
"version": "22.1.1",
|
|
4
4
|
"keywords": [
|
|
5
5
|
"angular",
|
|
6
6
|
"user-tracking",
|
|
@@ -18,9 +18,10 @@
|
|
|
18
18
|
"@angular/core": "^22.0.0"
|
|
19
19
|
},
|
|
20
20
|
"dependencies": {
|
|
21
|
+
"@su-labs/core": "1.8.0",
|
|
21
22
|
"tslib": "^2.3.0"
|
|
22
23
|
},
|
|
23
|
-
"homepage": "https://
|
|
24
|
+
"homepage": "https://su-labs.dev/visit-tracker/",
|
|
24
25
|
"author": {
|
|
25
26
|
"name": "Yevheniy Alekseyev",
|
|
26
27
|
"email": "yev.alekseyev@gmail.com",
|
|
@@ -1,36 +1,32 @@
|
|
|
1
|
+
import { SuVisitData, SuVisitTrackerConfig, SuVisitTrackerConfig as SuVisitTrackerConfig$1 } from "@su-labs/core/visit-tracker";
|
|
1
2
|
import * as i0 from "@angular/core";
|
|
2
|
-
import { WritableSignal } from "@angular/core";
|
|
3
|
+
import { OnDestroy, WritableSignal } from "@angular/core";
|
|
3
4
|
/**
|
|
4
|
-
*
|
|
5
|
+
* Angular service for tracking user visits.
|
|
6
|
+
*
|
|
7
|
+
* Thin wrapper around the framework-agnostic `SuVisitTrackerController` from
|
|
8
|
+
* `@su-labs/core/visit-tracker` that exposes the visit data as Angular signals.
|
|
5
9
|
*/
|
|
6
|
-
export
|
|
7
|
-
/**
|
|
8
|
-
|
|
9
|
-
/**
|
|
10
|
-
milestoneVisits?: number[];
|
|
11
|
-
}
|
|
12
|
-
/**
|
|
13
|
-
* Shape of the data stored in localStorage
|
|
14
|
-
*/
|
|
15
|
-
export interface SuVisitData {
|
|
16
|
-
count: number;
|
|
17
|
-
lastVisit: string;
|
|
18
|
-
}
|
|
19
|
-
export declare class SuVisitTrackerService {
|
|
20
|
-
/** Key used for localStorage */
|
|
21
|
-
private storageKey;
|
|
22
|
-
/** Milestones to track */
|
|
23
|
-
private _milestones;
|
|
24
|
-
/** Current visit count */
|
|
10
|
+
export declare class SuVisitTrackerService implements OnDestroy {
|
|
11
|
+
/** Framework-agnostic visit tracking logic */
|
|
12
|
+
private readonly controller;
|
|
13
|
+
/** Current visit count (0 until {@link init} runs) */
|
|
25
14
|
count: WritableSignal<number>;
|
|
26
|
-
/**
|
|
15
|
+
/** Start of the previous visit as an ISO string, or null on the first visit */
|
|
27
16
|
lastVisit: WritableSignal<string | null>;
|
|
28
17
|
/** The number of the milestone reached on the current visit, or null */
|
|
29
18
|
milestone: WritableSignal<number | null>;
|
|
30
|
-
/**
|
|
31
|
-
|
|
32
|
-
/**
|
|
33
|
-
|
|
19
|
+
/** Stops syncing the controller's state into the signals */
|
|
20
|
+
private readonly unsubscribe;
|
|
21
|
+
/**
|
|
22
|
+
* Record the current visit and update the signals.
|
|
23
|
+
* Call once at application startup.
|
|
24
|
+
* @param config Optional storage key and milestones.
|
|
25
|
+
*/
|
|
26
|
+
init(config?: SuVisitTrackerConfig$1): void;
|
|
27
|
+
/** Angular lifecycle hook for service destruction */
|
|
28
|
+
ngOnDestroy(): void;
|
|
34
29
|
static ɵfac: i0.ɵɵFactoryDeclaration<SuVisitTrackerService, never>;
|
|
35
30
|
static ɵprov: i0.ɵɵInjectableDeclaration<any>;
|
|
36
|
-
}
|
|
31
|
+
}
|
|
32
|
+
export type { SuVisitData, SuVisitTrackerConfig };
|