@tmlmobilidade/utils 20251031.1051.3 → 20251202.1817.5

package/README.md

@@ -1,13 +1,243 @@
-## @tmlmobilidade/utils
+# @tmlmobilidade/utils
 
-This package provides a collection of common utility functions used across projects within the organization.
+A collection of utility functions and helpers for the TML Mobilidade Go monorepo, providing common functionality for batching operations, caching, HTTP requests, object manipulation, permissions, and more.
 
-### Purpose
-- Centralize reusable logic
-- Promote consistency and reduce code duplication
-- Simplify development with well-tested, shared helpers
+## Installation
 
-### Installation
-```
+```bash
 npm install @tmlmobilidade/utils
-```
+```
+
+## Features
+
+### Batching
+
+Utilities for processing large datasets in chunks to avoid memory issues and improve performance.
+
+- **`performInChunks`** - Processes large arrays in configurable chunks with async operations
+
+### Caching
+
+In-memory cache implementation with TTL (time-to-live) support.
+
+- **`Cache`** - A simple key-value cache with automatic expiration
+
+### Generic Utilities
+
+Path-based object manipulation utilities with full TypeScript support.
+
+- **`getValueAtPath`** - Retrieves a value from an object using a dot-notation path
+- **`setValueAtPath`** - Sets a value at a dot-notation path, creating intermediate objects/arrays as needed
+- **`DotPath`** - TypeScript type for generating all possible paths in an object
+- **`PathValue`** - TypeScript type for retrieving the value type at a specific path
+
+### HTTP Utilities
+
+Comprehensive HTTP client utilities with retry logic, error handling, and SWR integration.
+
+- **`fetchData`** - Fetches data with automatic retry, exponential backoff, and error handling
+- **`multipartFetch`** - Sends multipart form data requests
+- **`uploadFile`** - Uploads files using multipart form data
+- **`swrFetcher`** - SWR-compatible fetcher with authentication
+- **`standardSwrFetcher`** - SWR-compatible fetcher without authentication
+- **`HttpResponse`** - Response wrapper with data, error, and status code
+- **`WithPagination`** - Type helper for paginated responses
+
+### Object Manipulation
+
+Utilities for comparing, converting, flattening, and merging objects.
+
+- **`compareObjects`** - Deep comparison of objects, returning differences
+- **`convertObject`** - Converts objects to match a Zod schema shape
+- **`flattenObject`** - Flattens nested objects using dot notation
+- **`mergeObjects`** - Deep merges objects and arrays with deduplication
+
+### Permissions
+
+Permission checking utilities for role-based access control.
+
+- **`getPermission`** - Retrieves a permission from a list by scope and action
+- **`hasPermission`** - Checks if a permission exists in a list
+- **`hasPermissionResource`** - Checks if a value exists in a permission's resource
+- **`hasAPIResourcePermission`** - Fastify-specific permission check for API resources
+
+### Singleton Proxy
+
+Utility for creating proxies around async singleton classes.
+
+- **`AsyncSingletonProxy`** - Creates a proxy that delays method access until singleton instance is initialized
+
+### Query Validation
+
+Utilities for validating and parsing query parameters.
+
+- **`validateQueryParams`** - Validates query parameters against a Zod schema
+
+## Usage Examples
+
+### Batching
+
+```typescript
+import { performInChunks } from '@tmlmobilidade/utils';
+
+const largeDataset = Array.from({ length: 10000 }, (_, i) => ({ id: i }));
+
+await performInChunks(largeDataset, async (chunk) => {
+  await processChunk(chunk);
+}, 1000); // Process 1000 items at a time
+```
+
+### Caching
+
+```typescript
+import { Cache } from '@tmlmobilidade/utils';
+
+const cache = new Cache<string, User>(60000); // 60 second TTL
+
+cache.set('user:123', user);
+const user = cache.get('user:123');
+cache.delete('user:123');
+```
+
+### Path Operations
+
+```typescript
+import { getValueAtPath, setValueAtPath } from '@tmlmobilidade/utils';
+
+const obj = { user: { profile: { name: 'John' } } };
+
+// Get nested value
+const name = getValueAtPath(obj, 'user.profile.name'); // 'John'
+
+// Set nested value (creates intermediate objects if needed)
+setValueAtPath(obj, 'user.profile.email', 'john@example.com');
+```
+
+### HTTP Requests
+
+```typescript
+import { fetchData, uploadFile, swrFetcher } from '@tmlmobilidade/utils';
+
+// GET request with retry
+const response = await fetchData<User>('/api/users/123');
+if (response.isOk()) {
+  console.log(response.data);
+}
+
+// POST request
+const createResponse = await fetchData<User>(
+  '/api/users',
+  'POST',
+  { name: 'John', email: 'john@example.com' }
+);
+
+// File upload
+const uploadResponse = await uploadFile<{ url: string }>('/api/upload', file);
+
+// SWR integration
+const data = await swrFetcher<User[]>('/api/users');
+```
+
+### Object Manipulation
+
+```typescript
+import { compareObjects, flattenObject, mergeObjects, convertObject } from '@tmlmobilidade/utils';
+import { z } from 'zod';
+
+// Compare objects
+const prev = { name: 'Alice', age: 30 };
+const curr = { name: 'Alice', age: 31 };
+const diff = compareObjects(prev, curr);
+// { age: { curr_value: 31, prev_value: 30 } }
+
+// Flatten object
+const nested = { a: { b: 1, c: { d: 2 } } };
+const flat = flattenObject(nested);
+// { 'a': { b: 1, c: { d: 2 } }, 'a.b': 1, 'a.c': { d: 2 }, 'a.c.d': 2 }
+
+// Merge objects
+const merged = mergeObjects({ a: 1, b: 2 }, { b: 3, c: 4 });
+// { a: 1, b: 3, c: 4 }
+
+// Convert to schema
+const schema = z.object({ name: z.string(), age: z.number() });
+const converted = convertObject({ name: 'John', age: 30, extra: 'ignored' }, schema);
+// { name: 'John', age: 30 }
+```
+
+### Permissions
+
+```typescript
+import { hasPermission, hasPermissionResource } from '@tmlmobilidade/utils';
+
+const permissions = [
+  { scope: 'users', action: 'read', resource: { userId: ['123', '456'] } },
+  { scope: 'users', action: 'write', resource: { userId: ['*'] } }
+];
+
+// Check if permission exists
+if (hasPermission(permissions, 'users', 'read')) {
+  // User has read permission
+}
+
+// Check resource-specific permission
+if (hasPermissionResource({
+  permissions,
+  scope: 'users',
+  action: 'read',
+  resource_key: 'userId',
+  value: '123'
+})) {
+  // User has permission for resource '123'
+}
+```
+
+### Query Validation
+
+```typescript
+import { validateQueryParams } from '@tmlmobilidade/utils';
+import { z } from 'zod';
+
+const schema = z.object({
+  page: z.coerce.number().min(1),
+  limit: z.coerce.number().min(1).max(100)
+});
+
+// In a Fastify route handler
+const params = validateQueryParams(req.query, schema);
+// Throws HttpException if validation fails
+```
+
+### Singleton Proxy
+
+```typescript
+import { AsyncSingletonProxy } from '@tmlmobilidade/utils';
+
+class Database {
+  private static instance: Database | null = null;
+  
+  static async getInstance(): Promise<Database> {
+    if (!this.instance) {
+      this.instance = await this.initialize();
+    }
+    return this.instance;
+  }
+  
+  async query(sql: string) {
+    // ...
+  }
+}
+
+// Create proxy that handles async initialization
+const db = AsyncSingletonProxy(Database);
+await db.query('SELECT * FROM users'); // Automatically waits for initialization
+```
+
+## License
+
+AGPL-3.0-or-later
+
+## Repository
+
+[GitHub](https://github.com/tmlmobilidade/go)
+

package/dist/{src/http.js → http.js}

@@ -1,4 +1,4 @@
-import { HttpException } from '@tmlmobilidade/lib';
+import { HttpException } from '@tmlmobilidade/consts';
 export class HttpResponse {
     data;
     error;

package/dist/index.d.ts

@@ -1,17 +1,8 @@
-export * from './src/batching/index.js';
-export * from './src/caching/index.js';
-export * from './src/css/index.js';
-export * from './src/dates/index.js';
-export * from './src/files/files.js';
-export * from './src/generic/index.js';
-export * from './src/geo/index.js';
-export * from './src/http.js';
-export * from './src/logs/index.js';
-export * from './src/math/index.js';
-export * from './src/navigation/index.js';
-export * from './src/objects/index.js';
-export * from './src/permissions.js';
-export * from './src/random/index.js';
-export * from './src/singleton-proxy.js';
-export * from './src/strings/index.js';
-export * from './src/validate-query-params.js';
+export * from './batching/index.js';
+export * from './caching/index.js';
+export * from './generic/index.js';
+export * from './http.js';
+export * from './objects/index.js';
+export * from './permissions.js';
+export * from './singleton-proxy.js';
+export * from './validate-query-params.js';

package/dist/index.js

@@ -1,17 +1,8 @@
-export * from './src/batching/index.js';
-export * from './src/caching/index.js';
-export * from './src/css/index.js';
-export * from './src/dates/index.js';
-export * from './src/files/files.js';
-export * from './src/generic/index.js';
-export * from './src/geo/index.js';
-export * from './src/http.js';
-export * from './src/logs/index.js';
-export * from './src/math/index.js';
-export * from './src/navigation/index.js';
-export * from './src/objects/index.js';
-export * from './src/permissions.js';
-export * from './src/random/index.js';
-export * from './src/singleton-proxy.js';
-export * from './src/strings/index.js';
-export * from './src/validate-query-params.js';
+export * from './batching/index.js';
+export * from './caching/index.js';
+export * from './generic/index.js';
+export * from './http.js';
+export * from './objects/index.js';
+export * from './permissions.js';
+export * from './singleton-proxy.js';
+export * from './validate-query-params.js';

package/dist/objects/fill-template.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Populates a template object with data from another object.
+ * @param template The template object to be populated.
+ * @param data The data object to populate the template with.
+ * @returns The populated template object.
+ */
+export default function fillTemplate<T>(template: T, data: any): T;

package/dist/objects/fill-template.js

@@ -0,0 +1,52 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Populates a template object with data from another object.
+ * @param template The template object to be populated.
+ * @param data The data object to populate the template with.
+ * @returns The populated template object.
+ */
+export default function fillTemplate(template, data) {
+    //
+    // Return the template if there is no data
+    if (!data)
+        return template;
+    // Create a deep copy of the template object
+    const populatedTemplateObject = JSON.parse(JSON.stringify(template));
+    // Setup a recursive function to populate the template
+    const recursivePopulate = (currentTemplateStep, currentDataStep) => {
+        //
+        // If the template is an object and not null
+        if (typeof currentTemplateStep === 'object' && currentTemplateStep !== null) {
+            //
+            // If the template is an array and the data is also an array, populate each element recursively
+            if (Array.isArray(currentTemplateStep) && Array.isArray(currentDataStep)) {
+                return currentDataStep?.map(item => recursivePopulate(currentTemplateStep, item));
+            }
+            // If the data is also an object, recursively populate its properties
+            if (typeof currentDataStep === 'object') {
+                const populatedInnerObject = {};
+                for (const key in currentTemplateStep) {
+                    populatedInnerObject[key] = recursivePopulate(currentTemplateStep[key], currentDataStep[key]);
+                }
+                return populatedInnerObject;
+            }
+            // If the data is null then use the template value
+            if (currentDataStep === null || currentDataStep === undefined) {
+                return currentTemplateStep;
+            }
+            // If it is something else use the data
+            return currentDataStep;
+            //
+        }
+        // If the template is not an object (i.e. an object or array) but data is null, use the template value
+        if (currentDataStep === null || currentDataStep === undefined) {
+            return currentTemplateStep;
+        }
+        // If the template is not an object and the data is defined, then use the data
+        return currentDataStep;
+        //
+    };
+    // Initiate the recursive dance
+    return recursivePopulate(populatedTemplateObject, data);
+    //
+}

package/dist/{src/objects → objects}/index.d.ts

@@ -1,4 +1,5 @@
 export * from './compare-objects.js';
 export * from './convert-object.js';
+export * from './fill-template.js';
 export * from './flatten-object.js';
 export * from './merge-objects.js';

package/dist/{src/objects → objects}/index.js

@@ -1,4 +1,5 @@
 export * from './compare-objects.js';
 export * from './convert-object.js';
+export * from './fill-template.js';
 export * from './flatten-object.js';
 export * from './merge-objects.js';

package/dist/permissions.d.ts

@@ -0,0 +1,46 @@
+import { type Permission } from '@tmlmobilidade/types';
+/**
+ * Get a scope and action filtered Permission object
+ * from a list of User permissions.
+ * @param permissions The full list of permissions of the user.
+ * @param scope The resource scope of the permission to filter by.
+ * @param action The action of the permission to filter by.
+ * @returns The filtered Permission object.
+ * @deprecated Use hasPermissionResource instead.
+ */
+export declare function getPermission(permissions: Permission[], scope: string, action: string): Permission;
+/**
+ * Arguments for hasPermissionResource function.
+ * @param T The type of the resource.
+ */
+export interface HasPermissionResourceArgs {
+    action: string;
+    permissions: Permission[];
+    resource_key: string;
+    scope: string;
+    value: unknown;
+}
+/**
+ * Check if a permission exists in a list of permissions, with additional check for a given resource value.
+ * If a `value` exists in a `resource` of a User `permissions` object that
+ * matches the given `action` and `scope`. For example, if you want to check if
+ * a user has access to a specific `agency_id`, you set `value=43` and `resource_key='agency_ids'`.
+ * If the provided `permissions` object contains the value `43` inside the `scope='plans'`,
+ * `action='create'` and `resource_key='agency_ids'` the function will return true.
+ * @param permissions The list of permissions (from a user or request).
+ * @param value The permission value to check against.
+ * @param resource_key The key of the resource.
+ * @param scope The scope of the permission.
+ * @param action The action of the permission.
+ * @returns The permission.
+ * @deprecated Use hasPermissionResource instead.
+ */
+export declare function hasPermissionResource({ action, permissions, resource_key, scope, value }: HasPermissionResourceArgs): boolean;
+/**
+ * Check if a value exists in a resource of a permission from Fastify request.
+ * @param request The FastifyRequest.
+ * @param params The parameters for checking permission.
+ * @returns True if the user has the requested permission, false otherwise.
+ * @deprecated Use hasPermissionResource instead.
+ */
+export declare function hasAPIResourcePermission(request: any, params: HasPermissionResourceArgs): boolean;

package/dist/permissions.js

@@ -0,0 +1,86 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* * */
+import { PermissionCatalog } from '@tmlmobilidade/types';
+import { mergekit } from 'mergekit';
+/**
+ * Get a scope and action filtered Permission object
+ * from a list of User permissions.
+ * @param permissions The full list of permissions of the user.
+ * @param scope The resource scope of the permission to filter by.
+ * @param action The action of the permission to filter by.
+ * @returns The filtered Permission object.
+ * @deprecated Use hasPermissionResource instead.
+ */
+export function getPermission(permissions, scope, action) {
+    return mergekit([...(permissions ?? [])], {
+        appendArrays: true,
+        dedupArrays: true,
+        onlyObjectWithKeyValues: [
+            { key: 'scope', value: scope },
+            { key: 'action', value: action },
+        ],
+    });
+}
+/**
+ * Check if a permission exists in a list of permissions, with additional check for a given resource value.
+ * If a `value` exists in a `resource` of a User `permissions` object that
+ * matches the given `action` and `scope`. For example, if you want to check if
+ * a user has access to a specific `agency_id`, you set `value=43` and `resource_key='agency_ids'`.
+ * If the provided `permissions` object contains the value `43` inside the `scope='plans'`,
+ * `action='create'` and `resource_key='agency_ids'` the function will return true.
+ * @param permissions The list of permissions (from a user or request).
+ * @param value The permission value to check against.
+ * @param resource_key The key of the resource.
+ * @param scope The scope of the permission.
+ * @param action The action of the permission.
+ * @returns The permission.
+ * @deprecated Use hasPermissionResource instead.
+ */
+export function hasPermissionResource({ action, permissions, resource_key, scope, value }) {
+    //
+    //
+    // Return false if no permissions
+    if (!permissions)
+        return false;
+    //
+    // Find the permission with the given action and scope
+    const foundPermission = permissions.find(permission => permission.action === action && permission.scope === scope);
+    if (!foundPermission)
+        return false;
+    //
+    // Check if value exists in the permission.resources[resource_key]
+    const resourceValues = foundPermission['resources']?.[resource_key];
+    if (!resourceValues)
+        return false;
+    //
+    // If resourceValues is an Array, check if value is in the array
+    // or if it contains the ALLOW_ALL_FLAG.
+    if (Array.isArray(resourceValues) && resourceValues.includes(PermissionCatalog.ALLOW_ALL_FLAG))
+        return true;
+    if (Array.isArray(resourceValues) && resourceValues.includes(value))
+        return true;
+    //
+    // If resourceValues is not an Array, check if it is equal to the requested value
+    if (resourceValues === value)
+        return true;
+    //
+    // Otherwise, return false
+    return false;
+    //
+}
+/**
+ * Check if a value exists in a resource of a permission from Fastify request.
+ * @param request The FastifyRequest.
+ * @param params The parameters for checking permission.
+ * @returns True if the user has the requested permission, false otherwise.
+ * @deprecated Use hasPermissionResource instead.
+ */
+export function hasAPIResourcePermission(request, params) {
+    return hasPermissionResource({
+        action: params.action,
+        permissions: request.permissions,
+        resource_key: params.resource_key,
+        scope: params.scope,
+        value: params.value,
+    });
+}

package/dist/{src/validate-query-params.js → validate-query-params.js}

@@ -1,4 +1,4 @@
-import { HttpException, HttpStatus } from '@tmlmobilidade/lib';
+import { HttpException, HttpStatus } from '@tmlmobilidade/consts';
 export function validateQueryParams(queryParams, schema) {
     const result = schema.safeParse(queryParams);
     if (!result.success) {

package/package.json

@@ -1,64 +1,50 @@
 {
 	"name": "@tmlmobilidade/utils",
-	"version": "20251031.1051.3",
-	"author": "João de Vasconcelos & Jusi Monteiro",
+	"version": "20251202.1817.5",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
 	"license": "AGPL-3.0-or-later",
-	"homepage": "https://github.com/tmlmobilidade/services#readme",
+	"homepage": "https://github.com/tmlmobilidade/go#readme",
 	"bugs": {
-		"url": "https://github.com/tmlmobilidade/services/issues"
+		"url": "https://github.com/tmlmobilidade/go/issues"
 	},
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/tmlmobilidade/services.git"
+		"url": "git+https://github.com/tmlmobilidade/go.git"
 	},
 	"keywords": [
 		"public transit",
 		"tml",
 		"transportes metropolitanos de lisboa",
-		"services"
+		"go"
 	],
 	"publishConfig": {
 		"access": "public"
 	},
 	"type": "module",
 	"files": [
-		"dist/"
+		"dist"
 	],
-	"exports": {
-		"types": "./dist/index.d.ts",
-		"default": "./dist/index.js"
-	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"scripts": {
-		"build": "rimraf ./dist && tsc && resolve-tspaths",
-		"lint": "eslint && tsc --noEmit",
-		"lint:fix": "eslint --fix"
-	},
-	"browser": {
-		"fs": false,
-		"os": false,
-		"path": false
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
 	},
 	"dependencies": {
-		"@tmlmobilidade/lib": "*",
-		"@turf/turf": "7.2.0",
-		"extract-zip": "2.0.1",
-		"geojson": "0.5.0",
-		"jszip": "3.10.1",
-		"luxon": "3.7.2",
-		"mergekit": "3.0.6",
-		"papaparse": "5.5.3",
-		"zod": "3.25.76"
+		"@tmlmobilidade/consts": "*",
+		"@tmlmobilidade/types": "*",
+		"mergekit": "3.0.6"
 	},
 	"devDependencies": {
-		"@carrismetropolitana/eslint": "20250622.1204.50",
 		"@tmlmobilidade/tsconfig": "*",
-		"@tmlmobilidade/types": "*",
-		"@types/luxon": "3.7.1",
-		"@types/node": "24.9.1",
-		"@types/papaparse": "5.3.16",
+		"@types/node": "24.10.1",
 		"resolve-tspaths": "0.8.23",
-		"rimraf": "6.0.1",
-		"turbo": "2.5.8",
+		"tsc-watch": "7.2.0",
 		"typescript": "5.9.3"
 	}
 }

package/dist/src/css/get-variable-value.d.ts

@@ -1 +0,0 @@
-export declare const getCssVariableValue: (variableName: string) => any;

package/dist/src/css/get-variable-value.js

@@ -1,8 +0,0 @@
-/* * */
-export const getCssVariableValue = (variableName) => {
-    if (typeof globalThis.window === 'undefined')
-        return undefined;
-    return globalThis.window.getComputedStyle(globalThis.document.documentElement)
-        .getPropertyValue(variableName)
-        .trim();
-};

package/dist/src/css/index.d.ts

@@ -1 +0,0 @@
-export * from './get-variable-value.js';

package/dist/src/css/index.js

@@ -1 +0,0 @@
-export * from './get-variable-value.js';