Commons Utilities

Shared utility functions and helpers used throughout the Feathers framework

The @feathersjs/commons package provides a collection of utility functions and helpers that are used throughout the Feathers ecosystem. These utilities offer lightweight alternatives to lodash-style operations and common JavaScript patterns.

Installation

npm install @feathersjs/commons

String Utilities

stripSlashes

Removes all leading and trailing slashes from a path string.

import { stripSlashes } from '@feathersjs/commons'

const path = stripSlashes('/api/users/')
console.log(path) // 'api/users'

name · string · required

The string to strip slashes from

return · string

The string with leading and trailing slashes removed

Object Utilities

The _ object provides a collection of utility functions for working with objects and arrays.

_.each

Iterates over an object or array and executes a callback for each element.

import { _ } from '@feathersjs/commons'

_.each({ name: 'John', age: 30 }, (value, key) => {
  console.log(`${key}: ${value}`)
})
// Output: name: John, age: 30

_.each(['a', 'b', 'c'], (value, index) => {
  console.log(`${index}: ${value}`)
})
// Output: 0: a, 1: b, 2: c

obj · any · required

The object or array to iterate over

callback · (value: any, key: string) => void · required

Function called for each element with value and key/index

_.some

Tests whether at least one element passes the test implemented by the callback.

import { _ } from '@feathersjs/commons'

const hasAdmin = _.some({ user1: 'admin', user2: 'user' }, (role) => role === 'admin')
console.log(hasAdmin) // true

value · any · required

The object to test

callback · (value: any, key: string) => boolean · required

Function to test each element

return · boolean

True if at least one element passes the test, false otherwise

_.every

Tests whether all elements pass the test implemented by the callback.

import { _ } from '@feathersjs/commons'

const allActive = _.every({ user1: 'active', user2: 'active' }, (status) => status === 'active')
console.log(allActive) // true

value · any · required

The object to test

callback · (value: any, key: string) => boolean · required

Function to test each element

return · boolean

True if all elements pass the test, false otherwise

_.keys

Returns an array of the object’s keys.

import { _ } from '@feathersjs/commons'

const keys = _.keys({ name: 'John', age: 30 })
console.log(keys) // ['name', 'age']

obj · any · required

The object to extract keys from

return · string[]

Array of object keys

_.values

Returns an array of the object’s values.

import { _ } from '@feathersjs/commons'

const values = _.values({ name: 'John', age: 30 })
console.log(values) // ['John', 30]

obj · any · required

The object to extract values from

return · any[]

Array of object values

_.isMatch

Checks if all properties in the item object match those in the source object.

import { _ } from '@feathersjs/commons'

const user = { name: 'John', age: 30, role: 'admin' }
const matches = _.isMatch(user, { name: 'John', age: 30 })
console.log(matches) // true

obj · any · required

The source object to check against

item · any · required

The object with properties to match

return · boolean

True if all item properties match obj properties

_.isEmpty

Checks if an object has no properties.

import { _ } from '@feathersjs/commons'

console.log(_.isEmpty({})) // true
console.log(_.isEmpty({ name: 'John' })) // false

obj · any · required

The object to check

return · boolean

True if the object has no keys

_.isObject

Checks if a value is a plain object (not an array or null).

import { _ } from '@feathersjs/commons'

console.log(_.isObject({})) // true
console.log(_.isObject([])) // false
console.log(_.isObject(null)) // false

item · any · required

The value to check

return · boolean

True if the value is a plain object

_.isObjectOrArray

Checks if a value is an object or array (not null).

import { _ } from '@feathersjs/commons'

console.log(_.isObjectOrArray({})) // true
console.log(_.isObjectOrArray([])) // true
console.log(_.isObjectOrArray(null)) // false

value · any · required

The value to check

return · boolean

True if the value is an object or array

_.extend

Shallow merges multiple objects into the first object.

import { _ } from '@feathersjs/commons'

const result = _.extend({ a: 1 }, { b: 2 }, { c: 3 })
console.log(result) // { a: 1, b: 2, c: 3 }

first · any · required

The target object to extend

rest · any[]

Additional objects to merge into the target

return · any

The extended target object

_.omit

Creates a new object with specified keys removed.

import { _ } from '@feathersjs/commons'

const user = { name: 'John', password: 'secret', age: 30 }
const safe = _.omit(user, 'password')
console.log(safe) // { name: 'John', age: 30 }

obj · any · required

The source object

keys · string[] · required

Keys to omit from the result

return · any

New object without the specified keys

_.pick

Creates a new object with only the specified keys.

import { _ } from '@feathersjs/commons'

const user = { name: 'John', password: 'secret', age: 30 }
const safe = _.pick(user, 'name', 'age')
console.log(safe) // { name: 'John', age: 30 }

source · any · required

The source object

keys · string[] · required

Keys to include in the result

return · any

New object with only the specified keys

_.merge

Recursively merges the source object into the target object.

import { _ } from '@feathersjs/commons'

const target = { 
  user: { name: 'John', settings: { theme: 'dark' } } 
}
const source = { 
  user: { settings: { language: 'en' } } 
}

_.merge(target, source)
console.log(target)
// { user: { name: 'John', settings: { theme: 'dark', language: 'en' } } }

target · any · required

The target object to merge into

source · any · required

The source object to merge from

return · any

The merged target object

Promise Utilities

isPromise

Duck-checks if an object looks like a promise.

import { isPromise } from '@feathersjs/commons'

console.log(isPromise(Promise.resolve())) // true
console.log(isPromise({ then: () => {} })) // true
console.log(isPromise(null)) // false

result · any · required

The value to check

return · boolean

True if the value has a then method

Symbol Utilities

createSymbol

Creates a symbol using Symbol.for() if available, otherwise returns the string.

import { createSymbol } from '@feathersjs/commons'

const sym = createSymbol('my-symbol')
console.log(typeof sym) // 'symbol'

name · string · required

The name for the symbol

return · symbol | string

A symbol created with Symbol.for(), or the name string if Symbol is unavailable

Debug Utilities

createDebug

Creates a debug function for a specific namespace.

import { createDebug } from '@feathersjs/commons'

const debug = createDebug('@myapp/users')

debug('User created:', { id: 1, name: 'John' })

name · string · required

The namespace for the debug function

return · DebugFunction

A debug function for the specified namespace

setDebug

Sets a custom debug initializer for all debug instances.

import { setDebug } from '@feathersjs/commons'
import debug from 'debug'

setDebug(debug)

debug · DebugInitializer · required

The debug initializer function

noopDebug

A no-operation debug function that does nothing.

import { noopDebug } from '@feathersjs/commons'

const debug = noopDebug()
debug('This will not output anything')

return · DebugFunction

A function that does nothing when called

Type Definitions

KeyValueCallback

Callback function type for object iteration methods.

type KeyValueCallback<T> = (value: any, key: string) => T

DebugFunction

Function type for debug logging.

type DebugFunction = (...args: any[]) => void

DebugInitializer

Function type for creating debug instances.

type DebugInitializer = (name: string) => DebugFunction