got returns of PunctualTimerReturns

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change logs
 
+## 2024.11.18 v5.23.0
+
+1. `punctualTimer` got returns of PunctualTimerReturns
+
 ## 2024.11.15 v5.22.1
 
 1. fix bugs of `nextVersion`

README.md

@@ -2557,6 +2557,8 @@ declare function nextVersion(
 
 punctual setInterval
 
+> v5.23.0 got returns of PunctualTimerReturns
+
 - Since: `5.18.0`
 
 - Arguments:
@@ -2567,13 +2569,15 @@ punctual setInterval
 | delay      | The time, in milliseconds that the timer should wait before the specified function or code is executed. If this parameter is omitted, a value of 0 is used, meaning execute "immediately", or more accurately, the next event cycle. | `number`   | -        | `true`   | -       |
 | ...args    | Additional arguments which are passed through to the function specified by handler.                                                                                                                                                  | `any[]`    | -        | `false`  | -       |
 
-- Returns: `void`
+- Returns: `PunctualTimerReturns`
 
 - Example:
 
 ```ts
 const printDate = () => console.log(new Date())
-punctualTimer(printDate, 1000)
+const timer = punctualTimer(printDate, 1000)
+console.log(timer.count) // 10
+timer.clear() // clear punctualTimer or use clearTimeout(timer.timer)
 ```
 
 - Types:
@@ -2583,12 +2587,19 @@ declare function punctualTimer<TArgs extends any[]>(
   handler: (args: void) => void,
   delay: number,
   [...args]?: TArgs
-): void
+): PunctualTimerReturns
+
 declare function punctualTimer<TArgs extends any[]>(
   handler: (...args: TArgs) => void,
   delay: number,
   [...args]?: TArgs
-): void
+): PunctualTimerReturns
+
+declare interface PunctualTimerReturns {
+  count: number
+  timer: number | null
+  clear: () => void
+}
 ```
 
 #### promiseFactory

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "js-cool",
 	"description": "Collection of common JavaScript / TypeScript utilities",
-	"version": "5.22.1",
+	"version": "5.23.0",
 	"packageManager": "pnpm@9.1.3",
 	"main": "dist/index.cjs.js",
 	"module": "dist/index.esm-bundler.js",

src/index.ts

@@ -112,7 +112,7 @@ export { default as getScrollPosition } from './getScrollPosition'
 // tools
 export { default as nextIndex } from './nextIndex'
 export { default as nextVersion, type Version } from './nextVersion'
-export { default as punctualTimer } from './punctualTimer'
+export { default as punctualTimer, type PunctualTimerReturns } from './punctualTimer'
 export { default as promiseFactory } from './promiseFactory'
 export { default as fixNumber } from './fixNumber'
 export { default as mapTemplate } from './mapTemplate'

src/punctualTimer.ts

@@ -1,10 +1,18 @@
+export interface PunctualTimerReturns {
+	count: number
+	timer: number | null
+	clear: () => void
+}
+
 /**
  * punctual setInterval
  *
  * @example
  * ```js
  * const printDate = () => console.log(new Date())
- * punctualTimer(printDate, 1000)
+ * const timer = punctualTimer(printDate, 1000)
+ * console.log(timer.count) // 10
+ * timer.clear() // clear punctualTimer or use clearTimeout(timer.timer)
  * ```
  * @since 5.18.0
  * @param handler - A function to be executed after the timer expires.
@@ -15,25 +23,41 @@ function punctualTimer<TArgs extends any[]>(
 	handler: (args: void) => void,
 	delay: number,
 	[...args]?: TArgs
-): void
+): PunctualTimerReturns
 function punctualTimer<TArgs extends any[]>(
 	handler: (...args: TArgs) => void,
 	delay: number,
 	[...args]?: TArgs
-): void
-function punctualTimer<TArgs extends any[]>(handler: any, delay: number, ...args: TArgs) {
+): PunctualTimerReturns
+function punctualTimer<TArgs extends any[]>(
+	handler: any,
+	delay: number,
+	...args: TArgs
+): PunctualTimerReturns {
 	handler()
-	let counter = 1
+	let _this: PunctualTimerReturns = {
+		count: 1,
+		timer: null,
+		clear() {
+			if (this.timer) {
+				clearTimeout(this.timer)
+				this.timer = null
+			}
+			_this = null as any
+			return _this
+		}
+	}
 	const start = new Date().getTime()
 	const instance = () => {
 		handler()
-		const ideal = counter * delay
+		const ideal = _this.count * delay
 		const real = new Date().getTime() - start
-		counter++
+		_this.count++
 		const diff = real - ideal
-		setTimeout(instance, delay - diff, ...args) // Repair by system time
+		_this.timer = setTimeout(instance, delay - diff, ...args) // Repair by system time
 	}
-	setTimeout(instance, delay, ...args)
+	_this.timer = setTimeout(instance, delay, ...args)
+	return _this
 }
 
 export default punctualTimer

src/randomString.ts

@@ -90,7 +90,7 @@ function randomString(
 		result = ''
 	if (typeof len !== 'number') {
 		options = len
-		len = typeof options === 'object' ? options.length ?? 32 : 32 // default
+		len = typeof options === 'object' ? (options.length ?? 32) : 32 // default
 	}
 	if (typeof options === 'boolean') {
 		if (options) charTypes.push('special')

src/spliceUrlParam.ts

@@ -44,7 +44,7 @@ function spliceUrlParam<T extends Record<string, unknown>>(
 	const result: string[] = []
 	for (key in params) {
 		if (typeof key === 'string') {
-			const val = '' + (covert ? params[key] ?? '' : params[key])
+			const val = '' + (covert ? (params[key] ?? '') : params[key])
 			result.push(`${key}=${encode ? encodeURIComponent(val) : val}`)
 		}
 	}