@tmlmobilidade/go-types-shared 20260722.1043.2 → 20260723.1350.16

package/dist/api/index.d.ts

@@ -0,0 +1 @@
+export * from './pagination.js';

package/dist/api/index.js

@@ -0,0 +1 @@
+export * from './pagination.js';

package/dist/conditions/exactly-one.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A type that represents exactly one key-value pair in the object T.
+ * @template T The type of the object.
+ * @example
+ * ```ts
+type Action = ExactlyOne<{
+  create: { name: string };
+  update: { id: string; name?: string };
+  delete: { id: string };
+}>;
+
+const x: Action = { create: { name: "New" } }; // ✅
+const y: Action = { update: { id: "123" } };   // ✅
+const z: Action = { create: { name: "X" }, delete: { id: "1" } }; // ❌
+ * ```
+ */
+export type ExactlyOne<T> = {
+    [K in keyof T]: Partial<Record<Exclude<keyof T, K>, never>> & {
+        [P in K]: T[P];
+    };
+}[keyof T];

package/dist/conditions/index.d.ts

@@ -0,0 +1,5 @@
+export * from './exactly-one.js';
+export * from './none-or-exactly-one.js';
+export * from './one-or-more.js';
+export * from './one-or-the-other.js';
+export * from './optional-if.js';

package/dist/conditions/index.js

@@ -0,0 +1,5 @@
+export * from './exactly-one.js';
+export * from './none-or-exactly-one.js';
+export * from './one-or-more.js';
+export * from './one-or-the-other.js';
+export * from './optional-if.js';

package/dist/conditions/none-or-exactly-one.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A type that represents either none or exactly one key-value pair in the object T.
+ * @template T The type of the object.
+ * @example
+ * ```ts
+ * type Filters = { name: string; age: number; email: string };
+ * type FilterChoice = NoneOrExactlyOne<Filters>;
+ *
+ * const a: FilterChoice = {}; // ✅ none
+ * const b: FilterChoice = { name: "Alice" }; // ✅ exactly one
+ * const c: FilterChoice = { age: 30 }; // ✅ exactly one
+ * const d: FilterChoice = { name: "Alice", age: 30 }; // ❌ error
+ * ```
+ */
+export type NoneOrExactlyOne<T> = {
+    [K in keyof T]: Partial<Record<Exclude<keyof T, K>, never>> & {
+        [P in K]: T[P];
+    };
+}[keyof T] | {
+    [K in keyof T]?: never;
+};

package/dist/conditions/none-or-exactly-one.js

@@ -0,0 +1 @@
+export {};

package/dist/conditions/one-or-more.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A type that represents either a single instance of type T or an array of type T.
+ * @template T The type of the element(s).
+ * @example
+ * ```ts
+ * function processItems<T>(items: OneOrMore<T>) {
+ *   const arr = Array.isArray(items) ? items : [items];
+ *   console.log(arr);
+ * }
+ *
+ * processItems("apple");      // ["apple"]
+ * processItems(["a", "b"]);   // ["a", "b"]
+ * ```
+ */
+export type OneOrMore<T> = T | T[];

package/dist/conditions/one-or-more.js

@@ -0,0 +1 @@
+export {};

package/dist/conditions/one-or-the-other.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A type that represents either A or B, but not both.
+ * @template A The first type.
+ * @template B The second type.
+ * @example
+ * ```ts
+ * type Credentials = OneOrTheOther<{ email: string }, { username: string }>;
+ *
+ * const a: Credentials = { email: "a@b.com" };    // ✅
+ * const b: Credentials = { username: "user1" };   // ✅
+ * const c: Credentials = { email: "a@b.com", username: "user1" }; // ❌
+ * ```
+ */
+export type OneOrTheOther<A, B> = (A & {
+    [K in keyof B]?: never;
+}) | (B & {
+    [K in keyof A]?: never;
+});

package/dist/conditions/one-or-the-other.js

@@ -0,0 +1 @@
+export {};

package/dist/conditions/optional-if.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Makes keys in `TFields` required when `TCondition` is absent,
+ * and optional when `TCondition` is present.
+ * @template T The base object type.
+ * @template TCondition The key that triggers optionality when present.
+ * @template TFields The keys that become optional when `TCondition` is present.
+ * @example
+ * ```ts
+ * type Lookup = OptionalIf<
+ *   { from: string; localField?: string; foreignField?: string; pipeline?: any[] },
+ *   'pipeline',
+ *   'localField' | 'foreignField'
+ * >;
+ *
+ * const a: Lookup = { from: "c", localField: "x", foreignField: "y" }; // ✅
+ * const b: Lookup = { from: "c", pipeline: [] }; // ✅
+ * const c: Lookup = { from: "c", pipeline: [], localField: "x" }; // ✅ (optional)
+ * const d: Lookup = { from: "c" }; // ❌ (localField/foreignField required when no pipeline)
+ * ```
+ */
+export type OptionalIf<T extends object, TCondition extends keyof T, TFields extends keyof T> = (Omit<T, TCondition | TFields> & Partial<Pick<T, TFields>> & Required<Pick<T, TCondition>>) | (Omit<T, TFields> & Required<Pick<T, TFields>> & {
+    [K in TCondition]?: never;
+});

package/dist/conditions/optional-if.js

@@ -0,0 +1 @@
+export {};

package/dist/dates/operational-date-int.d.ts

@@ -1,4 +1,7 @@
 import { z } from 'zod';
+/**
+ * The format for an operational date.
+ */
 export declare const OPERATIONAL_DATE_FORMAT = "yyyyMMdd";
 /**
  * Represents an operational date as an integer in the format 'yyyyMMdd'.
@@ -7,11 +10,37 @@ export declare const OPERATIONAL_DATE_FORMAT = "yyyyMMdd";
 export type OperationalDateInt = number & {
     __brand: 'OperationalDateInt';
 };
-export declare const OperationalDateIntSchema: z.ZodEffects<z.ZodNumber, OperationalDateInt, number>;
+/**
+ * The schema for an operational date value.
+ * @example
+ * ```ts
+ * const operationalDateInt = OperationalDateIntSchema.parse(20260620);
+ * // => 20260620 as OperationalDateInt
+ *
+ * const operationalDateInt = OperationalDateIntSchema.parse('20260620');
+ * // => 20260620 as OperationalDateInt
+ * ```
+ */
+export declare const OperationalDateIntSchema: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, OperationalDateInt, string | number>;
 /**
  * This function validates if a value is a valid operational date.
  * Throws an error if the value is invalid.
  * @param value The value to be validated.
  * @returns The given value as an OperationalDateInt.
+ * @throws An error if the value is invalid.
+ * @example
+ * ```ts
+ * const operationalDateInt = validateOperationalDateInt(20260620);
+ * // => 20260620 as OperationalDateInt
+ *
+ * const operationalDateInt = validateOperationalDateInt('20260620');
+ * // => 20260620 as OperationalDateInt
+ *
+ * const operationalDateInt = validateOperationalDateInt('2026-06-20');
+ * // => 20260620 as OperationalDateInt
+ *
+ * const operationalDateInt = validateOperationalDateInt('not a number');
+ * // => Throws an error: 'Invalid value 'not a number', expected a number or string in format 'yyyyMMdd' or a string in format 'yyyy-MM-dd', but received a NaN'
+ * ```
  */
 export declare function validateOperationalDateInt(value: number | string): OperationalDateInt;

package/dist/dates/operational-date-int.js

@@ -1,20 +1,49 @@
 /* * */
 import { DateTime } from 'luxon';
 import { z } from 'zod';
-/* * */
+/**
+ * The format for an operational date.
+ */
 export const OPERATIONAL_DATE_FORMAT = 'yyyyMMdd';
+/**
+ * The schema for an operational date value.
+ * @example
+ * ```ts
+ * const operationalDateInt = OperationalDateIntSchema.parse(20260620);
+ * // => 20260620 as OperationalDateInt
+ *
+ * const operationalDateInt = OperationalDateIntSchema.parse('20260620');
+ * // => 20260620 as OperationalDateInt
+ * ```
+ */
 export const OperationalDateIntSchema = z
-    .number()
+    .union([z.string(), z.number()])
     .transform(validateOperationalDateInt);
 /**
  * This function validates if a value is a valid operational date.
  * Throws an error if the value is invalid.
  * @param value The value to be validated.
  * @returns The given value as an OperationalDateInt.
+ * @throws An error if the value is invalid.
+ * @example
+ * ```ts
+ * const operationalDateInt = validateOperationalDateInt(20260620);
+ * // => 20260620 as OperationalDateInt
+ *
+ * const operationalDateInt = validateOperationalDateInt('20260620');
+ * // => 20260620 as OperationalDateInt
+ *
+ * const operationalDateInt = validateOperationalDateInt('2026-06-20');
+ * // => 20260620 as OperationalDateInt
+ *
+ * const operationalDateInt = validateOperationalDateInt('not a number');
+ * // => Throws an error: 'Invalid value 'not a number', expected a number or string in format 'yyyyMMdd' or a string in format 'yyyy-MM-dd', but received a NaN'
+ * ```
  */
 export function validateOperationalDateInt(value) {
+    const valueAsString = String(value).replaceAll('-', '');
     const parsedDate = DateTime.fromFormat(String(value), OPERATIONAL_DATE_FORMAT);
     if (!parsedDate.isValid)
         throw new Error(`Invalid date format '${value}', expected format: ${OPERATIONAL_DATE_FORMAT}, explanation: ${parsedDate.invalidExplanation}`);
-    return Number(value);
+    return Number(valueAsString);
 }

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

@@ -6,12 +6,38 @@ import { z } from 'zod';
 export type UnixTimestamp = number & {
     __brand: 'UnixTimestamp';
 };
-export declare const UnixTimestampSchema: z.ZodEffects<z.ZodNumber, UnixTimestamp, number>;
+/**
+ * The schema for a Unix timestamp value.
+ * @example
+ * ```ts
+ * const unixTimestamp = UnixTimestampSchema.parse(1715025600000);
+ * // => 1715025600000 as UnixTimestamp
+ *
+ * const unixTimestamp = UnixTimestampSchema.parse('1715025600000');
+ * // => 1715025600000 as UnixTimestamp
+ *
+ * const unixTimestamp = UnixTimestampSchema.parse('not a number');
+ * // => Throws an error: 'Invalid value 'not a number', expected a number or string in milliseconds, but received a NaN'
+ * ```
+ */
+export declare const UnixTimestampSchema: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, UnixTimestamp, string | number>;
 /**
  * This function validates if a number is a valid Unix Timestamp, in milliseconds.
  * It is assumed the number will always be greater than 10^10 (1e10) to ensure it is in milliseconds.
  * Throws an error if the date is invalid.
- * @param milliseconds - The number to be validated.
+ * @param value The number to be validated.
  * @returns The given number as a UnixTimestamp.
+ * @throws An error if the value is invalid.
+ * @example
+ * ```ts
+ * const unixTimestamp = validateUnixTimestamp(1715025600000);
+ * // => 1715025600000 as UnixTimestamp
+ *
+ * const unixTimestamp = validateUnixTimestamp('1715025600000');
+ * // => 1715025600000 as UnixTimestamp
+ *
+ * const unixTimestamp = validateUnixTimestamp('not a number');
+ * // => Throws an error: 'Invalid value 'not a number', expected a number in milliseconds but received a NaN'
+ * ```
  */
-export declare function validateUnixTimestamp(milliseconds: number): UnixTimestamp;
+export declare function validateUnixTimestamp(value: number | string): UnixTimestamp;

package/dist/dates/unix-timestamp.js

@@ -1,22 +1,50 @@
 /* * */
 import { DateTime } from 'luxon';
 import { z } from 'zod';
+/**
+ * The schema for a Unix timestamp value.
+ * @example
+ * ```ts
+ * const unixTimestamp = UnixTimestampSchema.parse(1715025600000);
+ * // => 1715025600000 as UnixTimestamp
+ *
+ * const unixTimestamp = UnixTimestampSchema.parse('1715025600000');
+ * // => 1715025600000 as UnixTimestamp
+ *
+ * const unixTimestamp = UnixTimestampSchema.parse('not a number');
+ * // => Throws an error: 'Invalid value 'not a number', expected a number or string in milliseconds, but received a NaN'
+ * ```
+ */
 export const UnixTimestampSchema = z
-    .coerce
-    .number()
+    .union([z.string(), z.number()])
     .transform(validateUnixTimestamp);
 /**
  * This function validates if a number is a valid Unix Timestamp, in milliseconds.
  * It is assumed the number will always be greater than 10^10 (1e10) to ensure it is in milliseconds.
  * Throws an error if the date is invalid.
- * @param milliseconds - The number to be validated.
+ * @param value The number to be validated.
  * @returns The given number as a UnixTimestamp.
+ * @throws An error if the value is invalid.
+ * @example
+ * ```ts
+ * const unixTimestamp = validateUnixTimestamp(1715025600000);
+ * // => 1715025600000 as UnixTimestamp
+ *
+ * const unixTimestamp = validateUnixTimestamp('1715025600000');
+ * // => 1715025600000 as UnixTimestamp
+ *
+ * const unixTimestamp = validateUnixTimestamp('not a number');
+ * // => Throws an error: 'Invalid value 'not a number', expected a number in milliseconds but received a NaN'
+ * ```
  */
-export function validateUnixTimestamp(milliseconds) {
-    if (milliseconds < 1e10)
-        throw new Error(`Invalid value '${milliseconds}', expected a number in milliseconds but received a number smaller than 1e10`);
-    const parsedDate = DateTime.fromMillis(milliseconds);
+export function validateUnixTimestamp(value) {
+    const valueAsNumber = Number(value);
+    if (Number.isNaN(valueAsNumber))
+        throw new Error(`Invalid value '${value}', expected a number in milliseconds but received a NaN`);
+    if (valueAsNumber < 1e10)
+        throw new Error(`Invalid value '${value}', expected a number in milliseconds but received a number smaller than 1e10`);
+    const parsedDate = DateTime.fromMillis(valueAsNumber);
     if (!parsedDate.isValid)
-        throw new Error(`Invalid date '${milliseconds}, explanation: ${parsedDate.invalidExplanation}`);
+        throw new Error(`Invalid UnixTimestamp value '${value}', explanation: ${parsedDate.invalidExplanation}`);
     return parsedDate.toMillis();
 }

package/dist/documents/comment.d.ts

@@ -20,9 +20,9 @@ export declare const NoteCommentSchema: z.ZodObject<{
     message: z.ZodString;
     type: z.ZodLiteral<"note">;
     _id: z.ZodOptional<z.ZodString>;
-    created_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    created_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     created_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    updated_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    updated_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     updated_by: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     message: string;
@@ -39,8 +39,8 @@ export declare const NoteCommentSchema: z.ZodObject<{
 }, {
     message: string;
     type: "note";
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     _id?: string | undefined;
     created_by?: string | null | undefined;
     updated_by?: string | undefined;
@@ -48,9 +48,9 @@ export declare const NoteCommentSchema: z.ZodObject<{
 export declare const FieldChangedCommentSchema: z.ZodObject<{
     type: z.ZodLiteral<"field_changed">;
     _id: z.ZodOptional<z.ZodString>;
-    created_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    created_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     created_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    updated_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    updated_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     updated_by: z.ZodOptional<z.ZodString>;
     curr_value: z.ZodAny;
     field: z.ZodString;
@@ -105,8 +105,8 @@ export declare const FieldChangedCommentSchema: z.ZodObject<{
     } | null | undefined;
 }, {
     type: "field_changed";
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     field: string;
     _id?: string | undefined;
     created_by?: string | null | undefined;
@@ -124,9 +124,9 @@ export declare const FieldChangedCommentSchema: z.ZodObject<{
 export declare const CrudCommentSchema: z.ZodObject<{
     type: z.ZodLiteral<"crud">;
     _id: z.ZodOptional<z.ZodString>;
-    created_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    created_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     created_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    updated_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    updated_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     updated_by: z.ZodOptional<z.ZodString>;
     action: z.ZodEnum<["create", "update", "delete", "archive", "restore"]>;
 }, "strip", z.ZodTypeAny, {
@@ -143,8 +143,8 @@ export declare const CrudCommentSchema: z.ZodObject<{
     updated_by?: string | undefined;
 }, {
     type: "crud";
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     action: "create" | "update" | "delete" | "archive" | "restore";
     _id?: string | undefined;
     created_by?: string | null | undefined;
@@ -154,9 +154,9 @@ export declare const CommentSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"type",
     message: z.ZodString;
     type: z.ZodLiteral<"note">;
     _id: z.ZodOptional<z.ZodString>;
-    created_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    created_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     created_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    updated_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    updated_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     updated_by: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     message: string;
@@ -173,17 +173,17 @@ export declare const CommentSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"type",
 }, {
     message: string;
     type: "note";
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     _id?: string | undefined;
     created_by?: string | null | undefined;
     updated_by?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"field_changed">;
     _id: z.ZodOptional<z.ZodString>;
-    created_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    created_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     created_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    updated_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    updated_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     updated_by: z.ZodOptional<z.ZodString>;
     curr_value: z.ZodAny;
     field: z.ZodString;
@@ -238,8 +238,8 @@ export declare const CommentSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"type",
     } | null | undefined;
 }, {
     type: "field_changed";
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     field: string;
     _id?: string | undefined;
     created_by?: string | null | undefined;
@@ -256,9 +256,9 @@ export declare const CommentSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"type",
 }>, z.ZodObject<{
     type: z.ZodLiteral<"crud">;
     _id: z.ZodOptional<z.ZodString>;
-    created_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    created_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     created_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    updated_at: z.ZodEffects<z.ZodNumber, import("../index.js").UnixTimestamp, number>;
+    updated_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../index.js").UnixTimestamp, string | number>;
     updated_by: z.ZodOptional<z.ZodString>;
     action: z.ZodEnum<["create", "update", "delete", "archive", "restore"]>;
 }, "strip", z.ZodTypeAny, {
@@ -275,8 +275,8 @@ export declare const CommentSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"type",
     updated_by?: string | undefined;
 }, {
     type: "crud";
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     action: "create" | "update" | "delete" | "archive" | "restore";
     _id?: string | undefined;
     created_by?: string | null | undefined;
@@ -329,15 +329,15 @@ export declare const CommentSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"type",
 }, {
     message: string;
     type: "note";
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     _id?: string | undefined;
     created_by?: string | null | undefined;
     updated_by?: string | undefined;
 } | {
     type: "field_changed";
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     field: string;
     _id?: string | undefined;
     created_by?: string | null | undefined;
@@ -353,8 +353,8 @@ export declare const CommentSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"type",
     } | null | undefined;
 } | {
     type: "crud";
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     action: "create" | "update" | "delete" | "archive" | "restore";
     _id?: string | undefined;
     created_by?: string | null | undefined;

package/dist/documents/document.d.ts

@@ -1,10 +1,10 @@
 import { z } from 'zod';
 export declare const DocumentSchema: z.ZodObject<{
     _id: z.ZodString;
-    created_at: z.ZodEffects<z.ZodNumber, import("../dates/unix-timestamp.js").UnixTimestamp, number>;
+    created_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../dates/unix-timestamp.js").UnixTimestamp, string | number>;
     created_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     is_locked: z.ZodDefault<z.ZodBoolean>;
-    updated_at: z.ZodEffects<z.ZodNumber, import("../dates/unix-timestamp.js").UnixTimestamp, number>;
+    updated_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, import("../dates/unix-timestamp.js").UnixTimestamp, string | number>;
     updated_by: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     _id: string;
@@ -19,8 +19,8 @@ export declare const DocumentSchema: z.ZodObject<{
     updated_by?: string | undefined;
 }, {
     _id: string;
-    created_at: number;
-    updated_at: number;
+    created_at: string | number;
+    updated_at: string | number;
     created_by?: string | null | undefined;
     is_locked?: boolean | undefined;
     updated_by?: string | undefined;

package/dist/documents/index.d.ts

@@ -0,0 +1,3 @@
+export * from './comment.js';
+export * from './document.js';
+export * from './proposed-change.js';

package/dist/documents/index.js

@@ -0,0 +1,3 @@
+export * from './comment.js';
+export * from './document.js';
+export * from './proposed-change.js';

package/dist/documents/proposed-change.d.ts

@@ -0,0 +1,120 @@
+import { type UnixTimestamp } from '../dates/unix-timestamp.js';
+import { type ApprovalStatus } from '../status/approval.js';
+import { z } from 'zod';
+export declare const ScopeSchema: z.ZodEnum<["stop", "lines"]>;
+export type Scope = z.infer<typeof ScopeSchema>;
+export declare const ProposedChangeSchema: z.ZodObject<{
+    _id: z.ZodString;
+    created_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, UnixTimestamp, string | number>;
+    created_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    is_locked: z.ZodDefault<z.ZodBoolean>;
+    updated_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, UnixTimestamp, string | number>;
+    updated_by: z.ZodOptional<z.ZodString>;
+} & {
+    curr_value: z.ZodAny;
+    field: z.ZodString;
+    related_id: z.ZodString;
+    scope: z.ZodEnum<["stop", "lines"]>;
+    status: z.ZodEnum<["pending", "approved", "rejected", "none"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "approved" | "rejected" | "none";
+    _id: string;
+    created_at: number & {
+        __brand: "UnixTimestamp";
+    };
+    created_by: string | null;
+    is_locked: boolean;
+    updated_at: number & {
+        __brand: "UnixTimestamp";
+    };
+    field: string;
+    related_id: string;
+    scope: "stop" | "lines";
+    updated_by?: string | undefined;
+    curr_value?: any;
+}, {
+    status: "pending" | "approved" | "rejected" | "none";
+    _id: string;
+    created_at: string | number;
+    updated_at: string | number;
+    field: string;
+    related_id: string;
+    scope: "stop" | "lines";
+    created_by?: string | null | undefined;
+    is_locked?: boolean | undefined;
+    updated_by?: string | undefined;
+    curr_value?: any;
+}>;
+export type ProposedChange<T> = {
+    [P in keyof T]: {
+        _id: string;
+        created_at: UnixTimestamp;
+        created_by: string;
+        curr_value: T[P];
+        field: P;
+        related_id: string;
+        scope: Scope;
+        status: ApprovalStatus;
+        updated_at: UnixTimestamp;
+        updated_by: string;
+    };
+}[keyof T];
+export declare const CreateProposedChangeSchema: z.ZodObject<Omit<{
+    _id: z.ZodString;
+    created_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, UnixTimestamp, string | number>;
+    created_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    is_locked: z.ZodDefault<z.ZodBoolean>;
+    updated_at: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, UnixTimestamp, string | number>;
+    updated_by: z.ZodOptional<z.ZodString>;
+} & {
+    curr_value: z.ZodAny;
+    field: z.ZodString;
+    related_id: z.ZodString;
+    scope: z.ZodEnum<["stop", "lines"]>;
+    status: z.ZodEnum<["pending", "approved", "rejected", "none"]>;
+}, "_id" | "created_at" | "updated_at">, "strip", z.ZodTypeAny, {
+    status: "pending" | "approved" | "rejected" | "none";
+    created_by: string | null;
+    is_locked: boolean;
+    field: string;
+    related_id: string;
+    scope: "stop" | "lines";
+    updated_by?: string | undefined;
+    curr_value?: any;
+}, {
+    status: "pending" | "approved" | "rejected" | "none";
+    field: string;
+    related_id: string;
+    scope: "stop" | "lines";
+    created_by?: string | null | undefined;
+    is_locked?: boolean | undefined;
+    updated_by?: string | undefined;
+    curr_value?: any;
+}>;
+export declare const UpdateProposedChangeSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<["pending", "approved", "rejected", "none"]>>;
+    is_locked: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    updated_by: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    curr_value: z.ZodOptional<z.ZodAny>;
+    field: z.ZodOptional<z.ZodString>;
+    related_id: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodEnum<["stop", "lines"]>>;
+}, "strip", z.ZodTypeAny, {
+    status?: "pending" | "approved" | "rejected" | "none" | undefined;
+    is_locked?: boolean | undefined;
+    updated_by?: string | undefined;
+    curr_value?: any;
+    field?: string | undefined;
+    related_id?: string | undefined;
+    scope?: "stop" | "lines" | undefined;
+}, {
+    status?: "pending" | "approved" | "rejected" | "none" | undefined;
+    is_locked?: boolean | undefined;
+    updated_by?: string | undefined;
+    curr_value?: any;
+    field?: string | undefined;
+    related_id?: string | undefined;
+    scope?: "stop" | "lines" | undefined;
+}>;
+export type CreateProposedChangeDto<T> = Omit<ProposedChange<T>, '_id' | 'created_at' | 'updated_at'>;
+export type UpdateProposedChangeDto<T> = Omit<CreateProposedChangeDto<T>, 'created_by'>;

package/dist/documents/proposed-change.js

@@ -0,0 +1,18 @@
+/* * */
+import { DocumentSchema } from './document.js';
+import { ApprovalStatusSchema } from '../status/approval.js';
+import { z } from 'zod';
+/* * */
+//
+// Define constants for enum values for better maintainability
+export const ScopeSchema = z.enum(['stop', 'lines']);
+// Define schemas using constants
+export const ProposedChangeSchema = DocumentSchema.extend({
+    curr_value: z.any(),
+    field: z.string(),
+    related_id: z.string(),
+    scope: ScopeSchema,
+    status: ApprovalStatusSchema,
+});
+export const CreateProposedChangeSchema = ProposedChangeSchema.omit({ _id: true, created_at: true, updated_at: true });
+export const UpdateProposedChangeSchema = CreateProposedChangeSchema.omit({ created_by: true }).partial();

package/dist/geo/index.d.ts

@@ -0,0 +1,2 @@
+export * from './latitude.js';
+export * from './longitude.js';

package/dist/geo/index.js

@@ -0,0 +1,2 @@
+export * from './latitude.js';
+export * from './longitude.js';

package/dist/geo/latitude.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+/**
+ * The latitude of a geographic coordinate, in degrees.
+ */
+export type Latitude = number & {
+    __brand: 'Latitude';
+};
+/**
+ * The schema for a latitude value.
+ * @example
+ * ```ts
+ * const latitude = LatitudeSchema.parse('40.712886213');
+ * // => 40.712886
+ *
+ * const latitude = LatitudeSchema.parse(40.712886213);
+ * // => 40.712886
+ *
+ * const latitude = LatitudeSchema.parse('94.7128');
+ * // => Throws an error: 'Latitude must be between -90 and 90'
+ */
+export declare const LatitudeSchema: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, Latitude, string | number>;
+/**
+ * Validate a latitude value.
+ * @param value The latitude value to validate.
+ * @throws An error if the latitude value is invalid.
+ * @returns The validated latitude value.
+ */
+export declare function validateLatitude(value: number | string): Latitude;

package/dist/geo/latitude.js

@@ -0,0 +1,32 @@
+/* * */
+import { z } from 'zod';
+/**
+ * The schema for a latitude value.
+ * @example
+ * ```ts
+ * const latitude = LatitudeSchema.parse('40.712886213');
+ * // => 40.712886
+ *
+ * const latitude = LatitudeSchema.parse(40.712886213);
+ * // => 40.712886
+ *
+ * const latitude = LatitudeSchema.parse('94.7128');
+ * // => Throws an error: 'Latitude must be between -90 and 90'
+ */
+export const LatitudeSchema = z
+    .union([z.string(), z.number()])
+    .transform(validateLatitude);
+/**
+ * Validate a latitude value.
+ * @param value The latitude value to validate.
+ * @throws An error if the latitude value is invalid.
+ * @returns The validated latitude value.
+ */
+export function validateLatitude(value) {
+    const valueAsNumber = parseFloat(String(value));
+    if (Number.isNaN(valueAsNumber))
+        throw new Error('Latitude must be a valid number');
+    if (valueAsNumber < -90 || valueAsNumber > 90)
+        throw new Error('Latitude must be between -90 and 90');
+    return Number(valueAsNumber.toFixed(6));
+}

package/dist/geo/longitude.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+/**
+ * The longitude of a geographic coordinate, in degrees.
+ */
+export type Longitude = number & {
+    __brand: 'Longitude';
+};
+/**
+ * The schema for a longitude value.
+ * @example
+ * ```ts
+ * const longitude = LongitudeSchema.parse('-9.55841684');
+ * // => -9.558416
+ *
+ * const longitude = LongitudeSchema.parse(-9.55841684);
+ * // => -9.558416
+ *
+ * const longitude = LongitudeSchema.parse('180.1');
+ * // => Throws an error: 'Longitude must be between -180 and 180'
+ */
+export declare const LongitudeSchema: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, Longitude, string | number>;
+/**
+ * Validate a longitude value.
+ * @param value The longitude value to validate.
+ * @throws An error if the longitude value is invalid.
+ * @returns The validated longitude value.
+ */
+export declare function validateLongitude(value: number | string): Longitude;

package/dist/geo/longitude.js

@@ -0,0 +1,32 @@
+/* * */
+import { z } from 'zod';
+/**
+ * The schema for a longitude value.
+ * @example
+ * ```ts
+ * const longitude = LongitudeSchema.parse('-9.55841684');
+ * // => -9.558416
+ *
+ * const longitude = LongitudeSchema.parse(-9.55841684);
+ * // => -9.558416
+ *
+ * const longitude = LongitudeSchema.parse('180.1');
+ * // => Throws an error: 'Longitude must be between -180 and 180'
+ */
+export const LongitudeSchema = z
+    .union([z.string(), z.number()])
+    .transform(validateLongitude);
+/**
+ * Validate a longitude value.
+ * @param value The longitude value to validate.
+ * @throws An error if the longitude value is invalid.
+ * @returns The validated longitude value.
+ */
+export function validateLongitude(value) {
+    const valueAsNumber = parseFloat(String(value));
+    if (Number.isNaN(valueAsNumber))
+        throw new Error('Longitude must be a valid number');
+    if (valueAsNumber < -180 || valueAsNumber > 180)
+        throw new Error('Longitude must be between -180 and 180');
+    return Number(valueAsNumber.toFixed(6));
+}

package/dist/index.d.ts

@@ -1,9 +1,7 @@
+export * from './api/index.js';
+export * from './conditions/index.js';
 export * from './dates/index.js';
-export * from './documents/comment.js';
-export * from './documents/document.js';
-export * from './environment.js';
-export * from './fastify.js';
-export * from './i18n-code.js';
-export * from './position.js';
+export * from './documents/index.js';
+export * from './geo/index.js';
 export * from './status/index.js';
-export * from './utility.js';
+export * from './utils/index.js';

package/dist/index.js

@@ -1,9 +1,7 @@
+export * from './api/index.js';
+export * from './conditions/index.js';
 export * from './dates/index.js';
-export * from './documents/comment.js';
-export * from './documents/document.js';
-export * from './environment.js';
-export * from './fastify.js';
-export * from './i18n-code.js';
-export * from './position.js';
+export * from './documents/index.js';
+export * from './geo/index.js';
 export * from './status/index.js';
-export * from './utility.js';
+export * from './utils/index.js';

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './environment.js';
+export * from './i18n-code.js';

package/dist/utils/index.js

@@ -0,0 +1,2 @@
+export * from './environment.js';
+export * from './i18n-code.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/go-types-shared",
-	"version": "20260722.1043.2",
+	"version": "20260723.1350.16",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"

package/dist/position.d.ts

@@ -1,160 +0,0 @@
-import z from 'zod';
-export declare const PositionSchema: z.ZodObject<{
-    geohash: z.ZodString;
-    h3: z.ZodString;
-    latitude: z.ZodNumber;
-    longitude: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    geohash: string;
-    h3: string;
-    latitude: number;
-    longitude: number;
-}, {
-    geohash: string;
-    h3: string;
-    latitude: number;
-    longitude: number;
-}>;
-export declare const ExtendedPositionSchema: z.ZodObject<{
-    geohash: z.ZodObject<{
-        geohash_2: z.ZodString;
-        geohash_3: z.ZodString;
-        geohash_4: z.ZodString;
-        geohash_5: z.ZodString;
-        geohash_6: z.ZodString;
-        geohash_7: z.ZodString;
-        geohash_8: z.ZodString;
-        geohash_9: z.ZodString;
-        geohash_10: z.ZodString;
-        geohash_11: z.ZodString;
-        geohash_12: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        geohash_2: string;
-        geohash_3: string;
-        geohash_4: string;
-        geohash_5: string;
-        geohash_6: string;
-        geohash_7: string;
-        geohash_8: string;
-        geohash_9: string;
-        geohash_10: string;
-        geohash_11: string;
-        geohash_12: string;
-    }, {
-        geohash_2: string;
-        geohash_3: string;
-        geohash_4: string;
-        geohash_5: string;
-        geohash_6: string;
-        geohash_7: string;
-        geohash_8: string;
-        geohash_9: string;
-        geohash_10: string;
-        geohash_11: string;
-        geohash_12: string;
-    }>;
-    h3: z.ZodObject<{
-        h3_1: z.ZodString;
-        h3_2: z.ZodString;
-        h3_3: z.ZodString;
-        h3_4: z.ZodString;
-        h3_5: z.ZodString;
-        h3_6: z.ZodString;
-        h3_7: z.ZodString;
-        h3_8: z.ZodString;
-        h3_9: z.ZodString;
-        h3_10: z.ZodString;
-        h3_11: z.ZodString;
-        h3_12: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        h3_1: string;
-        h3_2: string;
-        h3_3: string;
-        h3_4: string;
-        h3_5: string;
-        h3_6: string;
-        h3_7: string;
-        h3_8: string;
-        h3_9: string;
-        h3_10: string;
-        h3_11: string;
-        h3_12: string;
-    }, {
-        h3_1: string;
-        h3_2: string;
-        h3_3: string;
-        h3_4: string;
-        h3_5: string;
-        h3_6: string;
-        h3_7: string;
-        h3_8: string;
-        h3_9: string;
-        h3_10: string;
-        h3_11: string;
-        h3_12: string;
-    }>;
-    latitude: z.ZodNumber;
-    longitude: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    geohash: {
-        geohash_2: string;
-        geohash_3: string;
-        geohash_4: string;
-        geohash_5: string;
-        geohash_6: string;
-        geohash_7: string;
-        geohash_8: string;
-        geohash_9: string;
-        geohash_10: string;
-        geohash_11: string;
-        geohash_12: string;
-    };
-    h3: {
-        h3_1: string;
-        h3_2: string;
-        h3_3: string;
-        h3_4: string;
-        h3_5: string;
-        h3_6: string;
-        h3_7: string;
-        h3_8: string;
-        h3_9: string;
-        h3_10: string;
-        h3_11: string;
-        h3_12: string;
-    };
-    latitude: number;
-    longitude: number;
-}, {
-    geohash: {
-        geohash_2: string;
-        geohash_3: string;
-        geohash_4: string;
-        geohash_5: string;
-        geohash_6: string;
-        geohash_7: string;
-        geohash_8: string;
-        geohash_9: string;
-        geohash_10: string;
-        geohash_11: string;
-        geohash_12: string;
-    };
-    h3: {
-        h3_1: string;
-        h3_2: string;
-        h3_3: string;
-        h3_4: string;
-        h3_5: string;
-        h3_6: string;
-        h3_7: string;
-        h3_8: string;
-        h3_9: string;
-        h3_10: string;
-        h3_11: string;
-        h3_12: string;
-    };
-    latitude: number;
-    longitude: number;
-}>;
-export type Position = z.infer<typeof PositionSchema>;
-export type ExtendedPosition = z.infer<typeof ExtendedPositionSchema>;

package/dist/position.js

@@ -1,41 +0,0 @@
-import z from 'zod';
-/* * */
-export const PositionSchema = z.object({
-    geohash: z.string(),
-    h3: z.string(),
-    latitude: z.number(),
-    longitude: z.number(),
-});
-export const ExtendedPositionSchema = z.object({
-    geohash: z.object({
-        geohash_2: z.string(),
-        geohash_3: z.string(),
-        geohash_4: z.string(),
-        geohash_5: z.string(),
-        geohash_6: z.string(),
-        geohash_7: z.string(),
-        geohash_8: z.string(),
-        geohash_9: z.string(),
-        //
-        geohash_10: z.string(),
-        geohash_11: z.string(),
-        geohash_12: z.string(),
-    }),
-    h3: z.object({
-        h3_1: z.string(),
-        h3_2: z.string(),
-        h3_3: z.string(),
-        h3_4: z.string(),
-        h3_5: z.string(),
-        h3_6: z.string(),
-        h3_7: z.string(),
-        h3_8: z.string(),
-        h3_9: z.string(),
-        //
-        h3_10: z.string(),
-        h3_11: z.string(),
-        h3_12: z.string(),
-    }),
-    latitude: z.number(),
-    longitude: z.number(),
-});

package/dist/utility.d.ts

@@ -1,108 +0,0 @@
-/**
- * A type that represents either a single instance of type T or an array of type T.
- *
- * @template T - The type of the element(s).
- *
- * @example
- * ```ts
- * function processItems<T>(items: OneOrMore<T>) {
- *   const arr = Array.isArray(items) ? items : [items];
- *   console.log(arr);
- * }
- *
- * processItems("apple");      // ["apple"]
- * processItems(["a", "b"]);   // ["a", "b"]
- * ```
- */
-export type OneOrMore<T> = T | T[];
-/**
- * A type that represents either A or B, but not both.
- *
- * @template A - The first type.
- * @template B - The second type.
- *
- * @example
- * ```ts
- * type Credentials = OneOrTheOther<{ email: string }, { username: string }>;
- *
- * const a: Credentials = { email: "a@b.com" };    // ✅
- * const b: Credentials = { username: "user1" };   // ✅
- * const c: Credentials = { email: "a@b.com", username: "user1" }; // ❌
- * ```
- */
-export type OneOrTheOther<A, B> = (A & {
-    [K in keyof B]?: never;
-}) | (B & {
-    [K in keyof A]?: never;
-});
-/**
- * A type that represents exactly one key-value pair in the object T.
- *
- * @template T - The type of the object.
- *
- * @example
- * ```ts
-type Action = ExactlyOne<{
-  create: { name: string };
-  update: { id: string; name?: string };
-  delete: { id: string };
-}>;
-
-const x: Action = { create: { name: "New" } }; // ✅
-const y: Action = { update: { id: "123" } };   // ✅
-const z: Action = { create: { name: "X" }, delete: { id: "1" } }; // ❌
- * ```
- */
-export type ExactlyOne<T> = {
-    [K in keyof T]: Partial<Record<Exclude<keyof T, K>, never>> & {
-        [P in K]: T[P];
-    };
-}[keyof T];
-/**
- * A type that represents either none or exactly one key-value pair in the object T.
- *
- * @template T - The type of the object.
- *
- * @example
- * ```ts
- * type Filters = { name: string; age: number; email: string };
- * type FilterChoice = NoneOrExactlyOne<Filters>;
- *
- * const a: FilterChoice = {}; // ✅ none
- * const b: FilterChoice = { name: "Alice" }; // ✅ exactly one
- * const c: FilterChoice = { age: 30 }; // ✅ exactly one
- * const d: FilterChoice = { name: "Alice", age: 30 }; // ❌ error
- * ```
- */
-export type NoneOrExactlyOne<T> = {
-    [K in keyof T]: Partial<Record<Exclude<keyof T, K>, never>> & {
-        [P in K]: T[P];
-    };
-}[keyof T] | {
-    [K in keyof T]?: never;
-};
-/**
- * Makes keys in `TFields` required when `TCondition` is absent,
- * and optional when `TCondition` is present.
- *
- * @template T - The base object type.
- * @template TCondition - The key that triggers optionality when present.
- * @template TFields - The keys that become optional when `TCondition` is present.
- *
- * @example
- * ```ts
- * type Lookup = OptionalIf<
- *   { from: string; localField?: string; foreignField?: string; pipeline?: any[] },
- *   'pipeline',
- *   'localField' | 'foreignField'
- * >;
- *
- * const a: Lookup = { from: "c", localField: "x", foreignField: "y" }; // ✅
- * const b: Lookup = { from: "c", pipeline: [] }; // ✅
- * const c: Lookup = { from: "c", pipeline: [], localField: "x" }; // ✅ (optional)
- * const d: Lookup = { from: "c" }; // ❌ (localField/foreignField required when no pipeline)
- * ```
- */
-export type OptionalIf<T extends object, TCondition extends keyof T, TFields extends keyof T> = (Omit<T, TCondition | TFields> & Partial<Pick<T, TFields>> & Required<Pick<T, TCondition>>) | (Omit<T, TFields> & Required<Pick<T, TFields>> & {
-    [K in TCondition]?: never;
-});