@tmlmobilidade/utils 20250325.1729.16

package/README.md

@@ -0,0 +1,13 @@
+## @tmlmobilidade/utils
+
+This package provides a collection of common utility functions used across projects within the organization.
+
+### Purpose
+- Centralize reusable logic
+- Promote consistency and reduce code duplication
+- Simplify development with well-tested, shared helpers
+
+### Installation
+```
+npm install @tmlmobilidade/utils
+```

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './src/convert-object.js';
+export * from './src/generate-random-string.js';
+export * from './src/generate-random-token.js';
+export * from './src/operational-date.js';
+export * from './src/permissions.js';
+export * from './src/singleton-proxy.js';
+export * from './src/unix-timestamp.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+/* * */
+export * from './src/convert-object.js';
+export * from './src/generate-random-string.js';
+export * from './src/generate-random-token.js';
+export * from './src/operational-date.js';
+export * from './src/permissions.js';
+export * from './src/singleton-proxy.js';
+export * from './src/unix-timestamp.js';

package/dist/src/convert-object.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/**
+ * Convert an object to match a Zod schema's shape.
+ * @param source - The source object to convert
+ * @param template - The Zod schema to validate against
+ * @returns The converted object containing only the fields defined in the schema
+ * @throws {Error} If a required field is missing from the source object
+ */
+export declare function convertObject<T extends z.ZodObject<z.ZodRawShape>>(source: unknown, template: T): z.infer<T>;

package/dist/src/convert-object.js

@@ -0,0 +1,31 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Convert an object to match a Zod schema's shape.
+ * @param source - The source object to convert
+ * @param template - The Zod schema to validate against
+ * @returns The converted object containing only the fields defined in the schema
+ * @throws {Error} If a required field is missing from the source object
+ */
+export function convertObject(source, template) {
+    //
+    const templateKeys = Object.keys(template.shape);
+    const result = {};
+    for (const key of templateKeys) {
+        const fieldSchema = template.shape[key];
+        const value = source[key];
+        // Handle undefined/null values
+        if (value === undefined || value === null) {
+            if (!fieldSchema.nullish()) {
+                throw new Error(`Required field "${key}" is missing in the source object`);
+            }
+            continue;
+        }
+        const parsedValue = fieldSchema.safeParse(value);
+        if (!parsedValue.success) {
+            throw new Error(`Invalid field type for "${key}" in the source object:\n> ${parsedValue.error.errors.map(error => error.message).join('\n')}`);
+        }
+        // Add the value to result
+        result[key] = value;
+    }
+    return result;
+}

package/dist/src/generate-random-string.d.ts

@@ -0,0 +1,12 @@
+interface GenerateRandomStringOptions {
+    length?: number;
+    type?: 'alphanumeric' | 'numeric';
+}
+/**
+ * Creates a random string of a given length and type.
+ * @param length - The length of the string to generate.
+ * @param type - The type of characters to include in the string.
+ * @returns A random string of the specified length.
+ */
+export declare function generateRandomString({ length, type }?: GenerateRandomStringOptions): string;
+export {};

package/dist/src/generate-random-string.js

@@ -0,0 +1,27 @@
+/* * */
+/**
+ * Creates a random string of a given length and type.
+ * @param length - The length of the string to generate.
+ * @param type - The type of characters to include in the string.
+ * @returns A random string of the specified length.
+ */
+export function generateRandomString({ length = 6, type = 'alphanumeric' } = {}) {
+    //
+    const numericSet = '0123456789';
+    const alphanumericSet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+    let allowedCharacters;
+    switch (type) {
+        case 'numeric':
+            allowedCharacters = numericSet;
+            break;
+        default:
+            allowedCharacters = alphanumericSet;
+            break;
+    }
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result += allowedCharacters.charAt(Math.floor(Math.random() * allowedCharacters.length));
+    }
+    return result;
+    //
+}

package/dist/src/generate-random-token.d.ts

@@ -0,0 +1 @@
+export declare function generateRandomToken(): string;

package/dist/src/generate-random-token.js

@@ -0,0 +1,6 @@
+/* * */
+import { v4 as uuid } from 'uuid';
+/* * */
+export function generateRandomToken() {
+    return Buffer.from(uuid()).toString('base64');
+}

package/dist/src/operational-date.d.ts

@@ -0,0 +1,10 @@
+import { type OperationalDate } from '@tmlmobilidade/types';
+import { DateTime } from 'luxon';
+/**
+ * Returns the operational date based on the provided timestamp and format.
+ *
+ * @param timestamp - The timestamp to be parsed.
+ * @param format - The format of the timestamp.
+ * @returns The operational date in the yyyyLLdd format.
+ */
+export declare function getOperationalDate(timestamp?: DateTime | string, format?: string): OperationalDate;

package/dist/src/operational-date.js

@@ -0,0 +1,43 @@
+/* * */
+import { DateTime } from 'luxon';
+/**
+ * Returns the operational date based on the provided timestamp and format.
+ *
+ * @param timestamp - The timestamp to be parsed.
+ * @param format - The format of the timestamp.
+ * @returns The operational date in the yyyyLLdd format.
+ */
+export function getOperationalDate(timestamp, format) {
+    //
+    //
+    // Detect the type of the timestamp and parse it
+    let dateObject;
+    if (typeof timestamp === 'string' && format) {
+        dateObject = DateTime.fromFormat(timestamp, format);
+        if (!dateObject.isValid)
+            throw new Error(`Invalid date format '${timestamp}', expected format: ${format}, explanation: ${dateObject.invalidExplanation}`);
+    }
+    else if (timestamp && timestamp.isValid) {
+        dateObject = timestamp;
+    }
+    else {
+        dateObject = DateTime.now();
+    }
+    //
+    // Check if the time is between 00:00 and 03:59.
+    // The operational date is between 04:00 and 03:59 of the following day.
+    let operationalDate;
+    if (dateObject.hour < 4) {
+        // If true, return the previous day in the yyyyLLdd format
+        const previousDay = dateObject.minus({ days: 1 });
+        operationalDate = previousDay.toFormat('yyyyLLdd');
+    }
+    else {
+        // Else, return the current day in the yyyyLLdd format
+        operationalDate = dateObject.toFormat('yyyyLLdd');
+    }
+    //
+    // Validate the operational date and return it
+    return operationalDate;
+    //
+}

package/dist/src/permissions.d.ts

@@ -0,0 +1,9 @@
+import { type Permission } from '@tmlmobilidade/types';
+/**
+ * Get a permission from a list of permissions
+ * @param permissions - The list of permissions
+ * @param scope - The scope of the permission
+ * @param action - The action of the permission
+ * @returns The permission
+ */
+export declare function getPermission(permissions: Permission<unknown>[], scope: string, action: string): Permission<unknown>;

package/dist/src/permissions.js

@@ -0,0 +1,19 @@
+/* * */
+import { mergekit } from 'mergekit';
+/**
+ * Get a permission from a list of permissions
+ * @param permissions - The list of permissions
+ * @param scope - The scope of the permission
+ * @param action - The action of the permission
+ * @returns The permission
+ */
+export function getPermission(permissions, scope, action) {
+    return mergekit([...permissions], {
+        appendArrays: true,
+        dedupArrays: true,
+        onlyObjectWithKeyValues: [
+            { key: 'scope', value: scope },
+            { key: 'action', value: action },
+        ],
+    });
+}

package/dist/src/singleton-proxy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Creates a proxy for a singleton class that delays method access until the instance is initialized.
+ * @param cls - A class with a static `getInstance` method that returns a promise resolving to the class instance.
+ * @returns A proxy object that intercepts method calls and ensures the instance is initialized before invoking them.
+ */
+export declare function AsyncSingletonProxy<T extends object>(cls: {
+    getInstance: () => Promise<T>;
+}): T;

package/dist/src/singleton-proxy.js

@@ -0,0 +1,19 @@
+/**
+ * Creates a proxy for a singleton class that delays method access until the instance is initialized.
+ * @param cls - A class with a static `getInstance` method that returns a promise resolving to the class instance.
+ * @returns A proxy object that intercepts method calls and ensures the instance is initialized before invoking them.
+ */
+export function AsyncSingletonProxy(cls) {
+    return new Proxy({}, {
+        get: function (_target, prop, receiver) {
+            return async (...args) => {
+                const instance = await cls.getInstance();
+                const targetProp = Reflect.get(instance, prop, receiver);
+                if (typeof targetProp === 'function') {
+                    return targetProp.apply(instance, args);
+                }
+                return targetProp;
+            };
+        },
+    });
+}

package/dist/src/unix-timestamp.d.ts

@@ -0,0 +1,10 @@
+import { type OperationalDate, type UnixTimestamp } from '@tmlmobilidade/types';
+/**
+ * Returns the current Unix Timestamp, in milliseconds.
+ * @returns The current Unix Timestamp.
+ */
+export declare function getUnixTimestamp(): UnixTimestamp;
+export declare function getUnixTimestampFromOperationalDate(date: OperationalDate): UnixTimestamp;
+export declare function getUnixTimestampFromFormat(date: string, format: string): UnixTimestamp;
+export declare function getUnixTimestampFromJSDate(date: Date): UnixTimestamp;
+export declare function getUnixTimestampFromSeconds(seconds: number): UnixTimestamp;

package/dist/src/unix-timestamp.js

@@ -0,0 +1,34 @@
+/* * */
+import { OPERATIONAL_DATE_FORMAT } from '@tmlmobilidade/types';
+import { DateTime } from 'luxon';
+/**
+ * Returns the current Unix Timestamp, in milliseconds.
+ * @returns The current Unix Timestamp.
+ */
+export function getUnixTimestamp() {
+    return DateTime.now().toMillis();
+}
+export function getUnixTimestampFromOperationalDate(date) {
+    const parsedDate = DateTime.fromFormat(date, OPERATIONAL_DATE_FORMAT);
+    if (!parsedDate.isValid)
+        throw new Error(`Invalid date format '${date}', expected format: ${OPERATIONAL_DATE_FORMAT}, explanation: ${parsedDate.invalidExplanation}`);
+    return parsedDate.set({ hour: 4 }).toMillis();
+}
+export function getUnixTimestampFromFormat(date, format) {
+    const parsedDate = DateTime.fromFormat(date, format);
+    if (!parsedDate.isValid)
+        throw new Error(`Invalid date format '${date}', expected format: ${format}, explanation: ${parsedDate.invalidExplanation}`);
+    return parsedDate.toMillis();
+}
+export function getUnixTimestampFromJSDate(date) {
+    const parsedDate = DateTime.fromJSDate(date);
+    if (!parsedDate.isValid)
+        throw new Error(`Invalid date '${date}', explanation: ${parsedDate.invalidExplanation}`);
+    return parsedDate.toMillis();
+}
+export function getUnixTimestampFromSeconds(seconds) {
+    const parsedDate = DateTime.fromSeconds(seconds);
+    if (!parsedDate.isValid)
+        throw new Error(`Invalid date '${seconds}, explanation: ${parsedDate.invalidExplanation}`);
+    return parsedDate.toMillis();
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@tmlmobilidade/utils",
+	"version": "20250325.1729.16",
+	"author": "João de Vasconcelos & Jusi Monteiro",
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://github.com/tmlmobilidade/services#readme",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/services/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/services.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"services"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"module": "dist/src/index.js",
+	"files": [
+		"dist/"
+	],
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"build": "rimraf ./dist && tsc && resolve-tspaths",
+		"build:types": "npx tsx scripts/build-types.ts && npx rimraf ./dist && npx tsup --config tsup-types.config.ts",
+		"clean": "sh cleanup.sh",
+		"docker:local": "docker compose -f docker/local/compose.local.yaml up -d",
+		"docker:local-down": "docker compose -f docker/local/compose.local.yaml down",
+		"lint": "eslint && tsc --noEmit",
+		"lint:fix": "eslint --fix",
+		"test": "jest",
+		"test:prod": "jest --silent --coverage",
+		"test:watch": "jest --watch"
+	},
+	"dependencies": {
+		"luxon": "3.5.0",
+		"mergekit": "3.0.6",
+		"uuid": "11.1.0",
+		"zod": "3.24.2"
+	},
+	"devDependencies": {
+		"@carrismetropolitana/eslint": "20250303.2009.45",
+		"@tmlmobilidade/tsconfig": "*",
+		"@tmlmobilidade/types": "*",
+		"@types/luxon": "3.4.2",
+		"@types/node": "22.13.13",
+		"resolve-tspaths": "0.8.23",
+		"rimraf": "6.0.1",
+		"turbo": "2.4.4",
+		"typescript": "5.8.2"
+	}
+}