feat: add deprecation rule (#9278)

@types/premid/index.d.ts

@@ -554,17 +554,20 @@ declare class Presence {
   /**
    * Similar to `getTimestamps` but takes in a media element and returns snowflake timestamps
    * @param media Media object
+   * @deprecated since 2.7.5 - Use the standalone `getTimestampsFromMedia` function instead: import { getTimestampsFromMedia } from 'premid'
    */
   getTimestampsfromMedia(media: HTMLMediaElement): [number, number]
   /**
    * Converts time and duration integers into snowflake timestamps
    * @param {number} elementTime Current element time seconds
    * @param {number} elementDuration Element duration seconds
+   * @deprecated since 2.7.5 - Use the standalone `getTimestamps` function instead: import { getTimestamps } from 'premid'
    */
   getTimestamps(elementTime: number, elementDuration: number): [number, number]
   /**
    * Converts a string with format `HH:MM:SS` or `MM:SS` or `SS` into an integer (Does not return snowflake timestamp)
    * @param format The formatted string
+   * @deprecated since 2.7.5 - Use the standalone `timestampFromFormat` function instead: import { timestampFromFormat } from 'premid'
    */
   timestampFromFormat(format: string): number
   /**

eslint.config.mjs

@@ -56,4 +56,16 @@ export default antfu(
       'json-schema-validator/no-invalid': 'error',
     },
   },
+  {
+    files: ['websites/**/*.ts'],
+    languageOptions: {
+      parser: await import('@typescript-eslint/parser'),
+      parserOptions: {
+        project: './tsconfig.base.json',
+      },
+    },
+    rules: {
+      'ts/no-deprecated': 'error',
+    },
+  },
 )

premid/src/functions/getTimestamps.ts

@@ -0,0 +1,14 @@
+/**
+ * Converts current media time and duration into Unix timestamps
+ * @param {number} elementTime Current playback position in seconds
+ * @param {number} elementDuration Total duration of the media in seconds
+ * @returns {[number, number]} Array containing [startTimestamp, endTimestamp] as Unix timestamps in seconds
+ */
+export function getTimestamps(
+  elementTime: number,
+  elementDuration: number,
+): [startTimestamp: number, endTimestamp: number] {
+  const startTime = (Date.now() / 1000) - elementTime
+  const endTime = startTime + elementDuration
+  return [Math.floor(startTime), Math.floor(endTime)]
+}

premid/src/functions/getTimestampsFromMedia.ts

@@ -0,0 +1,16 @@
+import { getTimestamps } from './getTimestamps.js'
+
+/**
+ * Gets timestamps from an HTML media element (audio or video)
+ * @param {HTMLMediaElement} media The media element to get timestamps from (works with both <audio> and <video> elements)
+ * @returns {[number, number]} Array containing [startTimestamp, endTimestamp] as Unix timestamps in seconds
+ */
+export function getTimestampsFromMedia(
+  media: HTMLMediaElement,
+): [startTimestamp: number, endTimestamp: number] {
+  //* Return early if media is not loaded or has no duration
+  if (media.readyState === 0 || !Number.isFinite(media.duration))
+    return [0, 0]
+
+  return getTimestamps(media.currentTime, media.duration)
+}

premid/src/functions/timestampFromFormat.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts a time string into seconds
+ * @param {string} timestamp Time in format HH:MM:SS, MM:SS, or SS
+ * @returns {number} Time in seconds, or 0 if format is invalid
+ */
+export function timestampFromFormat(timestamp: string): number {
+  //* Handle invalid input
+  if (!timestamp || typeof timestamp !== 'string')
+    return 0
+
+  //* Check if format matches expected pattern
+  if (!/^\d+(?::\d{1,2}(?::\d{1,2})?)?$/.test(timestamp))
+    return 0
+
+  //* Split the timestamp into parts and pad from the left with zeros
+  const parts = timestamp.split(':').map(str => Number.parseInt(str, 10))
+  while (parts.length < 3) parts.unshift(0)
+
+  const [hours, minutes, seconds] = parts as [number, number, number]
+
+  //* Validate ranges
+  if (minutes >= 60 || seconds >= 60)
+    return 0
+
+  //* Convert everything to seconds
+  return (hours * 3600) + (minutes * 60) + seconds
+}

premid/src/index.ts

@@ -1,3 +1,7 @@
+export * from './functions/getTimestamps.js'
+export * from './functions/getTimestampsFromMedia.js'
+export * from './functions/timestampFromFormat.js'
+
 export enum ActivityType {
   /**
    * Playing {name}