feat(service-worker): add service worker utilities and logging support

.vscode/settings.json

@@ -54,6 +54,7 @@
     "argb",
     "backorder",
     "backordering",
+    "beforeinstallprompt",
     "colspan",
     "cssnano",
     "endmacro",

packages/service-worker/README.md

@@ -0,0 +1,121 @@
+# @nexim/alpine
+
+![NPM Version](https://img.shields.io/npm/v/%40nexim%2Falpine)
+![npm bundle size](https://img.shields.io/bundlephobia/min/%40nexim%2Falpine)
+![Build & Lint & Test](https://github.com/the-nexim/nanolib/actions/workflows/build-lint-test.yaml/badge.svg)
+![NPM Downloads](https://img.shields.io/npm/dm/%40nexim%2Falpine)
+![NPM License](https://img.shields.io/npm/l/%40nexim%2Falpine)
+
+## Overview
+
+`@nexim/alpine` is a versatile library designed to enhance your Alpine.js experience with a suite of utility functions and mixins. It provides robust solutions for data management, including logging capabilities and backup functionalities with local storage support. This library aims to streamline the development of high-performance projects, ensuring efficiency and scalability.
+
+## Installation
+
+Install the package using npm or yarn:
+
+```sh
+npm install @nexim/alpine
+
+# Or using yarn
+yarn add @nexim/alpine
+```
+
+## API
+
+### alpineStoreGenerator
+
+Generates an Alpine.js store with a default value.
+
+#### Example Usage
+
+```ts
+import {alpineStoreGenerator} from '@nexim/alpine';
+
+const store = alpineStoreGenerator({
+  name: 'user',
+  defaultValue: {type: 'root'},
+});
+
+console.log(store.type); // Output: root
+```
+
+### AlpineStore
+
+Provides a Alpine.js pure store implementation with logger.
+
+#### Constructor
+
+Creates an instance of `AlpineStore`.
+
+- **config**: The configuration object for the store.
+  - **name**: The name of the store.
+  - **defaultValue**: The default value of the store.
+
+### Properties
+
+- **store**: alpine store proxy.
+
+#### Example Usage
+
+```ts
+import {AlpineStore} from '@nexim/alpine';
+
+const {store} = new AlpineStore({
+  name: 'myStore',
+  defaultValue: {data: 'root'},
+});
+
+console.log(store.data); // Output: { data: 'root' }
+store.data = 'user';
+
+console.log(store.data); // Output: { data: 'user' }
+```
+
+### AlpineStoreWithBackup
+
+Extends `AlpineStore` to add backup and restore functionality with local storage support and expiration handling.
+
+#### Constructor
+
+Creates an instance of `AlpineStoreWithBackup`.
+
+- **config**: The configuration object for the store.
+  - **name**: The name of the store.
+  - **version**: The version of the store.
+  - **defaultValue**: The default value of the store.
+  - **expireDuration**: Optional. The duration after which the store expires.
+
+### Properties
+
+- **store**: alpine store proxy.
+
+#### Methods
+
+- **save()**: Saves the current data to local storage. If the data is null, it clears the stored data. Also updates the expiration time.
+- **clear()**: Clears the local storage and set default value to store.
+
+#### Example Usage
+
+```ts
+import {AlpineStoreWithBackup} from '@nexim/alpine';
+
+const storeWithBackup = new AlpineStoreWithBackup({
+  name: 'myStoreWithBackup',
+  version: 1,
+  defaultValue: {data: 'root'},
+  expireDuration: '1d',
+});
+
+storeWithBackup.store.data = 'user';
+
+storeWithBackup.save();
+console.log(storeWithBackup.store.data); // Output: { data: 'user' }
+
+storeWithBackup.clear();
+console.log(storeWithBackup.store.data); // Output: { data: 'root' }
+```
+
+### TODO
+
+- Analyze [@alwatr/context](https://github.com/Alwatr/flux/tree/next/packages/context) for use here.

packages/service-worker/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@nexim/service-worker",
+  "version": "0.0.0",
+  "description": "Utility functions to enhance Alpine.js usage with backup support.",
+  "keywords": [
+    "worker",
+    "service-worker",
+    "typescript",
+    "nexim"
+  ],
+  "homepage": "https://github.com/the-nexim/nanolib/tree/next/packages/service-worker#readme",
+  "bugs": {
+    "url": "https://github.com/the-nexim/nanolib/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/the-nexim/nanolib",
+    "directory": "packages/service-worker"
+  },
+  "license": "AGPL-3.0-only",
+  "author": "S. Amir Mohammad Najafi <njfamirm@gmail.com> (www.njfamirm.ir)",
+  "contributors": [
+    "Arash Ghardashpoor <arash.qardashpoor@gmail.com> (https://www.agpagp.ir)"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/main.mjs",
+      "require": "./dist/main.cjs"
+    }
+  },
+  "main": "./dist/main.cjs",
+  "module": "./dist/main.mjs",
+  "types": "./dist/main.d.ts",
+  "files": [
+    "**/*.{js,mjs,cjs,map,d.ts,html,md,LEGAL.txt}",
+    "LICENSE",
+    "!**/*.test.js",
+    "!demo/**/*"
+  ],
+  "scripts": {
+    "b": "yarn run build",
+    "build": "yarn run build:ts && yarn run build:es",
+    "build:es": "nano-build --preset=module",
+    "build:ts": "tsc --build",
+    "c": "yarn run clean",
+    "cb": "yarn run clean && yarn run build",
+    "clean": "rm -rfv dist *.tsbuildinfo",
+    "d": "yarn run build:es && yarn node --enable-source-maps --trace-warnings",
+    "t": "yarn run test",
+    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --enable-source-maps --experimental-vm-modules\" ava",
+    "w": "yarn run watch",
+    "watch": "yarn run watch:ts & yarn run watch:es",
+    "watch:es": "yarn run build:es --watch",
+    "watch:ts": "yarn run build:ts --watch --preserveWatchOutput"
+  },
+  "dependencies": {
+    "@alwatr/flux": "^4.0.2",
+    "@alwatr/i18n": "^2.0.4",
+    "@alwatr/local-storage": "^5.0.0",
+    "@alwatr/logger": "^5.0.0",
+    "@alwatr/package-tracer": "^5.0.0",
+    "@alwatr/parse-duration": "^5.0.0",
+    "@alwatr/wait": "^1.1.16",
+    "@nexim/snackbar": "workspace:^",
+    "alpinejs": "^3.14.7"
+  },
+  "devDependencies": {
+    "@alwatr/nano-build": "^5.0.0",
+    "@alwatr/type-helper": "^5.0.0",
+    "@nexim/typescript-config": "workspace:^",
+    "@types/alpinejs": "^3.13.11",
+    "ava": "^6.2.0",
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/service-worker/src/lib/install-pwa.ts

@@ -0,0 +1,130 @@
+import {parseDuration} from '@alwatr/parse-duration';
+import {waitForTimeout} from '@alwatr/wait';
+import {snackbarSignal} from '@nexim/snackbar';
+
+import {logger} from './logger.js';
+
+/**
+ * Type definition for BeforeInstallPromptEvent.
+ */
+interface BeforeInstallPromptEvent extends Event {
+  prompt: () => Promise<void>;
+  userChoice: Promise<void>;
+}
+
+/**
+ * Check if the app is running in installed PWA mode.
+ */
+function isOnInstalledPwa(): boolean {
+  return (
+    window.matchMedia('(display-mode: standalone)').matches ||
+    ('standalone' in window.navigator && window.navigator.standalone != null)
+  );
+}
+
+/**
+ * Check browser compatibility for PWA installation and setup the installation prompt handler.
+ * If the browser supports the `BeforeInstallPromptEvent` event, show the install button and handle the installation process.
+ * Requires an element with the `install-pwa-prompt` id.
+ */
+export function setupInstallPwaPromptHandler(): void {
+  logger.logMethod?.('setupInstallPwaPromptHandler');
+
+  if (isOnInstalledPwa() === true) return;
+
+  if (('BeforeInstallPromptEvent' in window) === false) return;
+
+  const installPwaPromptButton = document.getElementById('install-pwa-prompt');
+  if (installPwaPromptButton === null) return;
+
+  // Show button prompt because supported.
+  installPwaPromptButton.classList.remove('!hidden');
+  installPwaPromptButton.classList.add('!flex');
+
+  try {
+    let deferredPrompt: BeforeInstallPromptEvent | null = null;
+
+    window.addEventListener('beforeinstallprompt', (event: Event) => {
+      const beforeInstallPromptEvent = event as BeforeInstallPromptEvent;
+      beforeInstallPromptEvent.preventDefault();
+      deferredPrompt = beforeInstallPromptEvent;
+    });
+
+    installPwaPromptButton.addEventListener('click', () => {
+      if (deferredPrompt == null) {
+        logger.error('setupInstallPwaPromptHandler', 'deferred_prompt_is_null');
+        snackbarSignal.notify({
+          content: 'مشکلی در نصب برنامه پیش آمده است! ممکن است برنامه را قبلا نصب کرده باشید.',
+          duration: '2s',
+        });
+        waitForTimeout(parseDuration('3s')).then(() => {
+          location.href = '/';
+        });
+        return;
+      }
+
+      deferredPrompt.prompt();
+      deferredPrompt.userChoice.then(() => {
+        deferredPrompt = null;
+      });
+    });
+
+    window.addEventListener('appinstalled', () => {
+      deferredPrompt = null;
+      snackbarSignal.notify({
+        content: 'مراحل نصب آغاز شد...',
+      });
+
+      installPwaPromptButton.classList.add('!hidden');
+      installPwaPromptButton.classList.remove('!flex');
+    });
+  }
+  catch (error) {
+    logger.error('setupInstallPwaPromptHandler', 'unknown_install_error', {error});
+    snackbarSignal.notify({
+      content: 'مشکلی در نصب برنامه پیش آمده است! ممکن است برنامه را قبلا نصب کرده باشید.',
+    });
+  }
+}
+
+/**
+ * Show a guide link to install the PWA.
+ * Requires an element with the `install-pwa-guide` id.
+ */
+export function showInstallPwaGuideElement(): void {
+  logger.logMethod?.('showInstallPwaGuideElement');
+
+  if (isOnInstalledPwa() === true) return;
+
+  const installPwaGuideLink = document.getElementById('install-pwa-guide');
+  if (installPwaGuideLink === null) return;
+
+  installPwaGuideLink.classList.remove('!hidden');
+  installPwaGuideLink.classList.add('!flex');
+}
+
+/**
+ * Show a message that the PWA is installed.
+ * Requires an element with the `installed-pwa` id.
+ */
+export function showInstalledPwaMessage(): void {
+  logger.logMethod?.('showInstalledPwaMessage');
+
+  if (isOnInstalledPwa() === false) return;
+
+  const installedMessage = document.getElementById('installed-pwa');
+  if (installedMessage === null) return;
+
+  snackbarSignal.notify({
+    content: 'برنامه نصب شده است!',
+    action: {
+      label: 'رفتن به صفحه‌ی اصلی',
+      handler: () => {
+        location.href = '/';
+      },
+    },
+  });
+
+  installedMessage.classList.remove('!hidden');
+  installedMessage.classList.add('!flex');
+}

packages/service-worker/src/lib/logger.ts

@@ -0,0 +1,5 @@
+import {createLogger} from '@alwatr/logger';
+import {packageTracer} from '@alwatr/package-tracer';
+
+__dev_mode__: packageTracer.add(__package_name__, __package_version__);
+export const logger = /* @__PURE__ */ createLogger(`${__package_name__}:service-worker`);