@splendidlabz/utils 1.5.0-beta.6 → 1.5.1

package/lib/arrays/sort.js

@@ -1,10 +1,30 @@
 import { getNestedValue } from '../objects/nested-property.js'
+
 /**
- * Sorts an array of objects, numbers, or strings without mutating the original array
- * @param {Array} array - Array to sort
- * @param {Object} options - Sort options
- * @param {string|string[]|null} options.props - Property or array of properties to sort by. If null, sorts simple arrays
- * @param {boolean} options.reverse - Whether to sort in reverse order
+ * Sorts an array of objects, numbers, or strings without mutating the original array.
+ * Supports nested properties, multiple sort keys, and various data types.
+ * 
+ * @template T
+ * @param {T[]} array - Array to sort
+ * @param {Object} [options] - Sort options
+ * @param {string|string[]|null} [options.props=null] - Property or array of properties to sort by. If null, sorts simple arrays
+ * @param {boolean} [options.reverse=false] - Whether to sort in reverse order
+ * @returns {T[]} New sorted array
+ * @example
+ * // Sort simple array
+ * sort([3, 1, 2]) // [1, 2, 3]
+ * 
+ * // Sort objects by single property
+ * sort(users, { props: 'name' })
+ * 
+ * // Sort objects by multiple properties
+ * sort(users, { props: ['age', 'name'] })
+ * 
+ * // Sort in reverse order
+ * sort(users, { props: 'age', reverse: true })
+ * 
+ * // Sort by nested property
+ * sort(users, { props: 'address.city' })
  */
 export function sort(array, { props = null, reverse = false } = {}) {
   const clone = array.slice()
@@ -40,7 +60,15 @@ export function sort(array, { props = null, reverse = false } = {}) {
   })
 }
 
-// Compare values for sorting
+/**
+ * Compares two values for sorting, handling different data types.
+ * Supports numbers, strings, dates, and falls back to string comparison.
+ * 
+ * @param {*} a - First value to compare
+ * @param {*} b - Second value to compare
+ * @returns {number} -1 if a < b, 0 if a === b, 1 if a > b
+ * @private
+ */
 function compareValues(a, b) {
   // Compare numbers
   if (typeof a === 'number' && typeof b === 'number') return a - b
@@ -51,7 +79,9 @@ function compareValues(a, b) {
   // Compare dates
   const aDate = new Date(a)
   const bDate = new Date(b)
-  if (!isNaN(aDate) && !isNaN(bDate)) return aDate.getTime() - bDate.getTime()
+  const aTime = aDate.getTime()
+  const bTime = bDate.getTime()
+  if (!isNaN(aTime) && !isNaN(bTime)) return aTime - bTime
 
   // Convert into strings and compare
   return String(a).localeCompare(String(b))

package/lib/checks.js

@@ -1,11 +1,37 @@
+/**
+ * Checks if a value is a plain object (not an array or null)
+ * @param {unknown} x - The value to check
+ * @returns {boolean} True if the value is a plain object
+ * @example
+ * isObject({}) // true
+ * isObject([]) // false
+ * isObject(null) // false
+ */
 export function isObject(x) {
   return typeof x === 'object' && !Array.isArray(x) && x !== null
 }
 
+/**
+ * Checks if a value is an array
+ * @param {unknown} x - The value to check
+ * @returns {boolean} True if the value is an array
+ * @example
+ * isArray([]) // true
+ * isArray({}) // false
+ */
 export function isArray(x) {
   return Array.isArray(x)
 }
 
+/**
+ * Checks if a value is not a plain object
+ * @param {unknown} x - The value to check
+ * @returns {boolean} True if the value is not a plain object
+ * @example
+ * notObject([]) // true
+ * notObject(null) // true
+ * notObject({}) // false
+ */
 export function notObject(x) {
   return !isObject(x)
 }

package/lib/form/sanitize.js

@@ -1,9 +1,28 @@
 /**
- * Core sanitization function that handles different value types
+ * @typedef {Object} SanitizeOptions
+ * @property {Function} [sanitizer] - Function to sanitize strings
+ * @property {*} [additional] - Any additional properties are passed through to the sanitizer function
+ */
+
+/**
+ * Core sanitization function that handles different value types.
+ * Throws if no sanitizer function is provided.
+ * Any additional properties in options are passed through to the sanitizer function.
+ * 
  * @param {*} value - The value to sanitize
- * @param {Object} [options={}] - Sanitization options
- * @param {Function} options.sanitizer - Function to sanitize strings. Must be provided
+ * @param {SanitizeOptions} [options={}] - Sanitization options
+ * @throws {Error} If sanitizer function is not provided
  * @returns {*} Sanitized value
+ * @example
+ * // Basic sanitization
+ * sanitize('hello', { sanitizer: str => str.trim() })
+ * 
+ * // With additional options passed to sanitizer
+ * sanitize('hello', { 
+ *   sanitizer: (str, length, char) => str.padEnd(length, char),
+ *   length: 10,
+ *   char: '-'
+ * })
  */
 export function sanitize(value, options = {}) {
   const { sanitizer, ...rest } = options
@@ -22,12 +41,14 @@ export function sanitize(value, options = {}) {
   return value
 }
 /**
- * Sanitizes an array by recursively sanitizing each element
+ * Sanitizes an array by recursively sanitizing each element.
+ * Throws if no sanitizer function is provided.
+ * Any additional properties in options are passed through to the sanitizer function.
+ * 
  * @param {Array} arr - Array to sanitize
- * @param {Object} options - Sanitization options
- * @param {Function} options.sanitizer - Function to sanitize strings. Must be provided
- * @returns {Array} New array with sanitized values
+ * @param {SanitizeOptions} options - Sanitization options
  * @throws {Error} If sanitizer function is not provided
+ * @returns {Array} New array with sanitized values
  */
 function sanitizeArray(arr, { sanitizer, ...rest }) {
   if (!sanitizer) throw new Error('sanitizer function is required')
@@ -35,12 +56,14 @@ function sanitizeArray(arr, { sanitizer, ...rest }) {
 }
 
 /**
- * Sanitizes all string values in an object recursively
+ * Sanitizes all string values in an object recursively.
+ * Throws if no sanitizer function is not provided.
+ * Any additional properties in options are passed through to the sanitizer function.
+ * 
  * @param {Object} obj - Object to sanitize
- * @param {Object} [options={}] - Sanitization options
- * @param {Function} options.sanitizer - Function to sanitize strings. Must be provided
- * @returns {Object} New object with sanitized values
+ * @param {SanitizeOptions} [options={}] - Sanitization options
  * @throws {Error} If sanitizer function is not provided
+ * @returns {Object} New object with sanitized values
  */
 function sanitizeObject(obj, { sanitizer, ...options } = {}) {
   if (!sanitizer) throw new Error('sanitizer function is required')

package/lib/sse.js

@@ -1,4 +1,5 @@
 // Server Sent Events (SSE) 
+import { parseJSON } from './objects/json.js'
 import { omitEmpty } from './objects/omit-empty.js'
 
 export function createSSE({ event, data, id, retry }) {
@@ -22,7 +23,6 @@ export function createSSE({ event, data, id, retry }) {
  * @property {number} [retry] - The retry interval if specified
  */
 export function parseSSE(message) {
-  // console.log('parsing SSE', message);
   const lines = message.split('\n')
   const result = {
     event: 'message', // Default event type
@@ -34,10 +34,7 @@ export function parseSSE(message) {
   for (const line of lines) {
     if (line.startsWith('data:')) {
       const data = line.slice(5).trim()
-      // Try to parse as JSON
-      try { result.data = JSON.parse(data) } 
-      // If not JSON, use as string
-      catch { result.data = data }
+      result.data = parseJSON(data)
       continue
     } 
     
@@ -50,7 +47,7 @@ export function parseSSE(message) {
       result.id = line.slice(3).trim()
       continue
     } 
-    
+
     if (line.startsWith('retry:')) {
       result.retry = parseInt(line.slice(6).trim(), 10)
       continue
@@ -59,6 +56,6 @@ export function parseSSE(message) {
 
 
   const ret = omitEmpty(result)
-  // Only return if we have data
   return ret.data ? ret : null
 }
+

package/lib/strings/markdown.js

@@ -2,6 +2,13 @@ import { marked } from 'marked'
 import { gfmHeadingId } from 'marked-gfm-heading-id'
 import { mangle } from 'marked-mangle'
 
+/**
+ * Converts markdown content to HTML with whitespace handling
+ * @param {string} content - Markdown content to convert
+ * @param {Object} [options={}] - Conversion options
+ * @param {boolean} [options.inline=false] - Whether content should be treated as inline markdown
+ * @returns {string|Promise<string>} HTML string or Promise that resolves to HTML string
+ */
 export function markdown(content, options = {}) {
   const defaultOptions = { inline: false }
   const opts = { ...defaultOptions, ...options }
@@ -15,10 +22,11 @@ export function markdown(content, options = {}) {
 }
 
 /**
- * Removes leading whitespaces from a Markdown content so they can be rendered appropriately.
- * @param {string} content - The content to treat
- * @param {Boolean} options.inline - Whether content is inline, not block
- * @returns
+ * Handles whitespace in markdown content to ensure proper rendering
+ * @param {string} content - Markdown content to process
+ * @param {Object} [options={}] - Processing options
+ * @param {boolean} [options.inline=false] - Whether content is inline markdown
+ * @returns {{ content: string, inline: boolean }} Processed content and inline status
  */
 export function treatMarkdownWhitespace(content, { inline } = {}) {
   if (!content) return { content: '', inline }

package/node/file-cache.js

@@ -3,7 +3,18 @@ import glob from 'glob-promise'
 import path from 'node:path'
 import { sort } from '../lib/arrays/index.js'
 
-// Newer and nicer API
+/**
+ * Creates a file cache instance for managing cached files in a directory
+ * @param {string} dir - Relative path to cache directory
+ * @returns {Promise<object>} Cache instance
+ * @property {function(string): Promise<number>} cacheAt - Returns the cached file's modified timestamp, or directory's last modified time if no file specified
+ * @property {function(string): string} getAbsPath - Returns absolute path for a file in cache
+ * @property {function(string): Promise<boolean>} hasFile - Checks if a file exists in cache
+ * @property {function(string): Promise<Buffer|undefined>} loadFile - Loads file contents from cache
+ * @property {function(string, string|Buffer): Promise<void>} saveFile - Saves data to cache file
+ * @property {function(string): Promise<object>} loadJSON - Loads and parses JSON from cache file
+ * @property {function(string, object): Promise<void>} saveJSON - Saves object as JSON to cache file
+ */
 export async function createCache(dir) {
   const absDirpath = path.join(process.cwd(), dir)
   await fs.mkdir(absDirpath, { recursive: true })
@@ -56,7 +67,7 @@ export async function createCache(dir) {
     async loadJSON(file) {
       const data = await this.loadFile(file)
       try {
-        return JSON.parse(data)
+        return JSON.parse(data.toString())
       } catch (err) {
         console.warn(`Error parsing JSON: ${file}`)
         return {}
@@ -69,7 +80,19 @@ export async function createCache(dir) {
   }
 }
 
-// Legacy, not so nice API
+/**
+ * Legacy file cache API for managing a single cached file
+ * @param {Object} options
+ * @param {string} options.dir - Relative path to cache directory
+ * @param {string} options.file - Filename to cache
+ * @returns {Promise<{
+ *   modifiedAt: number,
+ *   load: () => Promise<Buffer>,
+ *   save: (data: string|Buffer) => Promise<void>,
+ *   loadJSON: () => Promise<object>,
+ *   saveJSON: (data: object) => Promise<void>
+ * }>}
+ */
 export async function fileCache({ dir, file }) {
   // Makes the path if it doesn't exist
   await fs.mkdir(path.join(process.cwd(), dir), { recursive: true })
@@ -94,7 +117,8 @@ export async function fileCache({ dir, file }) {
     },
 
     async loadJSON() {
-      return JSON.parse(await fs.readFile(cachePath))
+      const data = await fs.readFile(cachePath)
+      return JSON.parse(data.toString())
     },
     async saveJSON(data) {
       await fs.writeFile(cachePath, JSON.stringify(data))
@@ -102,6 +126,11 @@ export async function fileCache({ dir, file }) {
   }
 }
 
+/**
+ * Gets the most recent modification time of files matching the glob pattern
+ * @param {string|string[]} globPath - Glob pattern(s) to match files
+ * @returns {Promise<number>} Timestamp of most recently modified file, or 0 if no files found
+ */
 export async function getLastModifiedTime(globPath) {
   let files
 
@@ -116,13 +145,18 @@ export async function getLastModifiedTime(globPath) {
     files = a.flat()
   }
 
-  files = await Promise.all(files.map(fs.stat))
-  files = files.map(file => file.mtimeMs)
+  const stats = await Promise.all(files.map(file => fs.stat(file)))
+  const timestamps = stats.map(stat => Number(stat.mtimeMs))
 
-  const sorted = sort(files, { props: 'mtimeMs', reverse: true })
+  const sorted = sort(timestamps, { props: 'mtimeMs', reverse: true })
   return sorted[0] || 0
 }
 
+/**
+ * @deprecated Use getLastModifiedTime instead
+ * @param {string|string[]} globPath - Glob pattern(s) to match files
+ * @returns {Promise<number>} Timestamp of most recently modified file, or 0 if no files found
+ */
 export async function getLatestModifiedTime(globPath) {
   console.warn(
     '`getLatestModifiedTime` has been renamed to `getLastModifiedTime` and will be deprecated in future versions. Please use `getLastModifiedTime` instead.',
@@ -130,6 +164,11 @@ export async function getLatestModifiedTime(globPath) {
   return getLastModifiedTime(globPath)
 }
 
+/**
+ * Removes leading slash from a path string
+ * @param {string} x - Path string to process
+ * @returns {string} Path without leading slash
+ */
 export function removeFirstSlash(x) {
   return x.startsWith('/') ? x.slice(1) : x
 }

package/node/sanitize.js

@@ -9,5 +9,5 @@ import { sanitize as sanitizeLib } from '../lib/form/sanitize.js'
  * @throws {Error} If input is a string but sanitize-html fails
  */
 export function sanitize(value, options = {}) {
-  return sanitizeLib(value, { sanitizer: sanitizeHtml })
+  return sanitizeLib(value, { sanitizer: sanitizeHtml, ...options })
 }

package/package.json

@@ -1,21 +1,42 @@
 {
   "name": "@splendidlabz/utils",
-  "version": "1.5.0-beta.6",
+  "version": "1.5.1",
   "description": "",
   "type": "module",
   "sideEffects": false,
   "exports": {
-    ".": "./lib/index.js",
-    "./lib/*": "./lib/*.js",
-    "./dom": "./dom/index.js",
-    "./dom/*": "./dom/*.js",
-    "./node": "./node/index.js",
-    "./node/*": "./node/*.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./lib/*": {
+      "types": "./dist/lib/*.d.ts",
+      "import": "./lib/*.js"
+    },
+    "./dom": {
+      "types": "./dist/dom/index.d.ts",
+      "import": "./dom/index.js"
+    },
+    "./dom/*": {
+      "types": "./dist/dom/*.d.ts",
+      "import": "./dom/*.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./node/index.js"
+    },
+    "./node/*": {
+      "types": "./dist/node/*.d.ts",
+      "import": "./node/*.js"
+    }
   },
   "scripts": {
     "lint": "eslint . --fix",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "npm run type-check && vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
   },
   "author": "Zell Liew <zellwk@gmail.com>",
   "dependencies": {
@@ -30,9 +51,10 @@
     "statuses": "^2.0.1"
   },
   "devDependencies": {
-    "@splendidlabz/eslint-config": "2.0.0-alpha.1",
+    "@splendidlabz/eslint-config": "2.0.0",
     "jsdom": "^26.0.0",
     "np": "^10.2.0",
+    "typescript": "^5.4.2",
     "vitest": "^3.1.1"
   }
 }

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist",
+    "strict": false,
+    "noImplicitAny": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["lib/**/*", "dom/**/*", "node/**/*"],
+  "exclude": ["node_modules", "**/*.test.js", "**/*.spec.js"]
+}