ö.js
ö.js - a small collection of useful stuff.
Usage:
(p)npm install ouml
import { random } from 'ouml'
let oneOrZero = random()
or, with treeshaking:
import * as ö from 'ouml'
let oneOrZero = ö.random()
Most methods are runnable within node/deno. Some methods require browser API:s, those are marked with [browser].
Modules
Includes modules chain, a method for chaining calls on any type, öbservable, a basic implementation of reactive values, övents, a collection of useful custom browser events, and colour, a simple way to work with oklch colours.
Import them from
import chain, { chainAsync } from 'ouml/chain'
import { observable, isObservable, observe } from 'ouml/öbservable'
import {
resize,
enterview,
exitview,
sticktotop,
sticktobottom,
swipe,
clickoutside,
} from 'ouml/övents'
import colour, { isColour } from 'ouml/colour'
Methods
Generators / Iterators
Helper methods for iterations, less verbose than regular loops.
ö.range( start, end?, step? = 1 ) yields Number
Yields Number
s within specified range. Parameters end
and step
are optional. If end
is not provided, range starts with 0
, and ends with start
. Handles negative values. Useful in for of
loops, for example:
for (let i of ö.range(100)) doStuff(i)
ö.grid( width, height? ) yields { x, y }
Yields Object
with x, y
coordinates. If height
is omitted, width
is assumed. Use like so:
for (let i of ö.grid(8)) drawChessboard(i.x, i.y)
ö.times( times, f? = i => i, ...rest ) → Array
Calls a function times
times, with index
as argument. Additional arguments are passed on to f
like so:
ö.times(100, (i, a, b) => i + a + b, 'a', 'b')
Returns an array containing the return values of f
, or an array containing index values if f
is undefined
.
Array / Iterable
Methods for manipulating arrays or array-like objects. Inputs are coerced to Array
, so String
, Set
and the like works as input as well. All methods are non-mutating.
ö.rangeArray( start, end?, step? = 1 ) → Array
Returns an Array
populated with given range.
ö.map( iterable | obj, f | str ) → Iterable | obj.key
Same as a normal map, except it accepts a string
as a shorthand for retrieving values from an object property, if given an iterable that contains objects. Oh, and it accepts all iterables, and returns String
, Map
, Set
and TypedArray
as appropriate. It's a map
for Map
! Edge case iterables such as NodeList
get converted to an array.
Oh, and it's a map
for Object
s! In the rare case that you would mant to map over the own properties of an object, that also works.
ö.map({ a: 1, b: 2 }, ([k, v]) => [k, v + 1]) // returns { a: 2, b: 3 }
Mapping functions for Map
s and Object
s receive an array in the form of [key, val]
as a value argument, and must return an array in the same format.
ö.unique( arr ) → Array
Returns an Array
with unique entries.
ö.shuffle( arr ) → Array
Returns a new shuffled Array
.
ö.sample( arr, samples? = 1 ) → Array item | Array
Returns random sample from arr
, or an array of samples if samples
is larger than one.
ö.sum( arr ) → Number
Sums arr
, with Number
coercion.
ö.mean( arr ) → Number
Calculates mean value of arr
, with Number
coercion.
ö.product( arr ) → Number
Returns product of arr
, with Number
coercion. Reaches Number.MAX_VALUE
rather quickly for large arrays, so use with some caution.
ö.geometricMean( arr ) → Number
Calculates the geometric mean of arr
, with Number
coercion. May return Infinity
for large arrays or large numbers, since it uses ö.product
.
ö.median( arr ) → Number
Calculates median value of arr
, with Number
coercion.
ö.max( arr ) → Number
Returns largest value in arr
.
ö.min( arr ) → Number
Returns smallest value in arr
.
ö.groupBy( arr, prop | f, asObject? = false) → Map | Object
Returns a Map
with keys corresponding to prop
values, holding grouped values as arrays. Optionally returns an object
if asObject
is set to true.
If prop
is a string, takes an iterable of object
s with a common property. If prop
is a function, takes a function returning keys for grouping based on arr
contents. The function receives value, index, array
as arguments.
Tree structures
ö.mapToTree( arr, idProp | f, parentProp?) → Nested array
Maps a flat array of objects to a tree structure. Objects with children get a new children
property, unsurprisingly containing an array of children 🙄. Leaf nodes have no children
property. Works in one of two ways:
Either you provide an idProp
and a parentProp
, where the ìdProp
holds a value unique to every item in the array, and parentProp
holds a reference to the parent's idProp
value (useful for example if you get a flattened hierarchic list from an api).
Or, you provide a mapping function responsible for providing a unique key for the item, and a unique key for the parent. The function receives value, index, array
as arguments, and should produce an array with [ ownKey, parentKey ]
. If the item has no parent, set parentKey
to null
. Useful for example for mapping urls to a hierarchy.
Parentless children (orphans) will be discarded.
Example:
let flat = [
{ id: '1' },
{ id: '1.1', parent: '1' },
{ id: '1.1.1', parent: '1.1' },
{ id: '2' },
{ id: '2.2', parent: '2' },
]
let tree = ö.mapToTree(flat, 'id', 'parent')
// or
let sameTree = ö.mapToTree(flat, item => [
item.id,
item.id.split('.').slice(0, -1).join('.'),
])
ö.reduceDeep( arr, f, subArrayProp, initial? ) → value
Reduces arrays of nested objects to a single value. subArrayProp
is a string
matching the property containing nested arrays.
The reducer function f
receives accumulator, value, index, array
as arguments. initial
can be omitted, just like the native reduce
, in that case the first item of arr
is used as the initial value.
Example:
let arr = [
{
value: 1,
children: [
{ value: 1 },
{ value: 1 },
{ value: 1, children: [{ value: -4 }] },
],
},
]
ö.reduceDeep(arr, (acc, v) => acc + v.value, 'children', 0) // returns 0
ö.mapDeep( arr, f | prop, subArrayProp, flatten? = false ) → Array
Maps over arrays of nested objects. subArrayProp
is a string
matching the property containing nested arrays.
If f
is a function, its return value is mapped to a new array. The function receives value, index, array
as arguments. If f
returns an object
, and flatten
is false
, the structure of the original arr
is preserved, and a property matching subArrayProp
is added to the object, containing its children.
If f
is a string
, the value of the property matching f
is returned, in a flattened array.
ö.filterDeep( arr, f | value, subArrayProp, prop? ) → Array
Finds items that match f
in arrays of nested objects. subArrayProp
is a string
matching the property containing nested arrays.
If f
is a function, returns items where f
returns true
. The function receives value, index, array
as arguments. If f
is a function, prop
can be omitted.
If f
is not a function, the value of f
is compared to the value of property prop
.
Returns a flat array with matching items, regardless of depth.
ö.findDeep( arr, f | value, subArrayProp, prop? ) → Array item
Same as ö.filterDeep
, except it returns first match.
Set operations
Methods for comparing arrays or array-like objects. Inputs are coerced to Set
. All methods return a new Array
, or Boolean
.
The outputs adhere to strict set logic. If the inputs are Array
s, duplicate items are removed. All these methods are wrappers around internal Set
methods, but returns arrays. (Available in evergreens and in node 22+)
ö.intersect( a, b ) → Array
Intersection, returns elements that are members of both a
and b
.
Example:
ö.intersect([0, 1], [1, 2]) // returns [1]
ö.subtract( a, b ) → Array
Difference, returns members of a
but not members of b
, i.e. subtracts b
from a
.
Example:
ö.subtract([0, 1], [1, 2]) // returns [0]
ö.exclude( a, b ) → Array
Symmetric difference, returns elements that are members of a
or b
, but not both.
Example:
ö.exclude([0, 1], [1, 2]) // returns [0, 2]
ö.union( a, b ) → Array
Returns (unique) members of both a
and b
.
Example:
ö.union([0, 1], [1, 2]) // returns [0, 1, 2]
ö.isSubset( a, b ) → Boolean
Returns true
if a
is a subset of b
.
ö.isSuperset( a, b ) → Boolean
Returns true
if a
is a superset of b
.
ö.isDisjoint( a, b ) → Boolean
Returns true
if a
and b
share no members.
Logical / generic / functional
ö.isEqual/ö.equals( a, b, deep? = true ) → Boolean
Checks equality by value rather than reference. Compares prototypes, and uses Reflect.ownKeys
to compare all own keys, including symbols. Works for all basic types and most built in classes, but may produce unexpected results in edge cases. Equality is tricky, and depends on what you personally beleive to be equal 😇. Does deep comparison by default, and may be slow for large data structures. If deep == false
, does flat comparison instead.
ö.clone( v, deep? = true, immutable? = false ) → cloned value
Performs cloning of most common types, including Array
and typed arrays, Map
, Set
, Date
and objects. Defaults to deep cloning, set deep
to false
for shallow cloning. Tries to preserve prototype
when cloning objects, but may fail in untested edge cases. Set preservePrototype
to false to disable this (this is somewhat faster). Does not clone functions, and doesn't handle circular references. Use with some caution 🤫.
The native structuredClone
is probably slower (by alot!) in most cases, errors on functions, and doesn't preserve prototype, but it handles circular references. Choose wisely!
ö.immutable( v, deep? = true ) → immutable value
Returns a freezed clone of v
. Set deep
to false
to make only top level immutable.
ö.id( v ) → v
Identity, takes and returns v
.
ö.pipe( v, ...funcs ) → value
Pipes function calls for a value. For multiple arguments, use closures. Usage:
ö.pipe(
1,
x => x * 6,
x => x ** 2,
x => x + 6,
ö.log,
) // logs 42
ö.toPiped( ...funcs ) → function( v ) → value
Pipes function calls, and returns a function that takes the value to pipe. The data last save for later version of pipe. Usage:
const myPipe = ö.toPiped(
x => x * 6,
x => x ** 2,
x => x + 6,
ö.log,
)
myPipe(1) // logs 42
ö.pipeAsync( v, ...funcs ) → Promise
Same as ö.pipe
, but awaits functions and returns a Promise
.
ö.toPipedAsync( ...funcs ) → function( v ) → Promise
Pipes function calls, and returns a function that takes the value to pipe. That function returns a Promise
.
ö.curry( f ) → function
Returns a curried version of f
, allowing partial application of arguments. If f
takes three arguments, it can be called like so:
const f = (a, b, c) => a + b + c
const curried = ö.curry(f)
curried(1)(2)(3) // returns 6
// or
const partial = curried(1, 2)
partial(3) // also 6
ö.memoise/ö.memoize( f, keymaker? ) → f
Creates and returns memoised functions. By default, the arguments to the memoised function are used as key for storing the result (If only one argument, the raw input is used as key, if more than one, the arguments are joined to a string). If the arguments are objects instead of primitive values, you should provide a keymaker
. keymaker
receives all inputs from the memoised function, and should return something unique to use as a Map
key for a given set of inputs. Use for example JSON.stringify
when you expect objects as input.
ö.createEnum( object ) → Object
Creates and returns an enumerable, i.e. a frozen object where the keys have unique values. Lets you create kinda sorta vanilla typechecking light, but at runtime 🤪. Takes an object, or strings, or an array of strings, as input. In order for codehinting to work, you need to provide an explicit object. Example:
const SIZES = ö.createEnum('small', 'medium', 'large')
// or:
const SIZES = ö.createEnum(['small', 'medium', 'large'])
// or:
const SIZES = ö.createEnum({
small: Symbol('small'),
medium: Symbol('medium'),
large: Symbol('large'),
})
giveMeIcecream(SIZES.large)
ö.data( obj, key?, value? ) → data | data.key
Associates obj
(Can be an Object
or a Symbol
) with data via a WeakMap
. With only key
set, acts as a getter for key
. With key
and value
set, acts as a setter. Useful for associating data with DOM elements. If given an Element
, it parses the dataset
property and adds its properties to data
.
If no key
, returns data
object.
Mathy
ö.random( min, max, float? = false ) → integer | Number
Shorthand for random integers between min
and max
-1. If max
is omitted or Boolean
, assumes a min
value of 0. If max
is Boolean
, float
is assumed. If float
is true, returns float instead of integer.
ö.randomNormal( mean? = 0, sigma? = 1 ) → Number
Returns random number from reasonably approximated normal distribution, centered around mean
, with more or less 68.2% of the sample set within ± sigma
. Values max out at a bit above ± 3 sigma
, with extreme outliers up to about ± 4 sigma
. There are more mathematically accurate methods to do this, but this method is fast, and good enough for most people. Use it for fun and visuals, not for statistical analysis 🤓.
ö.round( n, precision? = 0 ) → Number
Returns n
rounded to precision
decimals.
ö.clamp( n, min, max ) → Number
Clamps n
between min
and max
.
ö.between( n, min, max ) → Boolean
Checks if n
is between min
and up to, but not including, max
.
ö.normalise/ö.normalize( n, min, max, clamp? = true ) → Number
Normalises n
to a value between 0 and 1, within range given by min
and max
. If clamp == true
and value of n
is out of range, the value is clamped.
ö.lerp( a, b, t ) → Number
Interpolates linearly between a
and b
. t
is a percentage value between 0 and 1.
ö.smoothstep( a, b, t ) → Number
Interpolates smoothly between a
and b
. t
is a percentage value between 0 and 1.
ö.easeIn( a, b, t ) → Number
Eases in from a
to b
. t
is a percentage value between 0 and 1.
ö.easeOut( a, b, t ) → Number
Eases out from a
to b
. t
is a percentage value between 0 and 1.
ö.nthRoot( x, n ) → Number
Returns nth root of positive number, for example
ö.nthRoot(256, 8) === 2
ö.factorial( n ) → Number
Returns the factorial of n
.
ö.nChooseK( n, k ) → Number
Returns the number of ways to choose k
elements from a set of n
elements, i.e. the binomial coefficient.
ö.toPolar(x, y) → { r, theta }
Converts cartesian coordinates to polar.
ö.toCartesian(r, theta) → { x, y }
Converts polar coordinates to cartesian.
String
ö.prettyNumber( n, locale? = 'sv-SE', precision? = 2 ) → String
Returns n
rounded to precision
decimals and formatted by n.toLocaleString()
. Defaults to swedish formatting, because why not! locale
is optional, if second argument is Number
, precision
is set instead.
ö.wrapFirstWords( s, numWords? = 3, startWrap? = '<span>', endWrap? = '</span>', startAtChar? = 0 ) → String
Returns s
with first numWords
words wrapped in startWrap
and endWrap
. Matches first words up to and including first punctuation. Optionally starts matching at index startAtChar
. Matches special chars for nordic languages as well as ', ’ and -.
ö.toCamelCase( str ) → String
Returns regular sentence, kebab-case or snake_case string converted to camelCase. Leaves --custom-properties
alone.
ö.capitalise/ö.capitalize( str ) → String
Capitalises first letter. No fuss!
ö.toKebabCase( str ) → String
Returns regular sentence or camelCase string converted to kebab-case. Leaves --customProperties
alone.
ö.randomChars( numChars? = 10 ) → String
Returns numChars
random characters. Max for numChars
is 100. Useful for producing unique values (Or, to be precise, with a 1/426 825 223 812 027 400 796 974 891 518 773 732 340 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 chance of being a dupe 🤯).
ö.stripTags( str ) → String
Returns a string without html tags.
ö.when( bool, whenTrue, whenFalse? ) → value | empty string;
A slightly more readable wrapper around a ternary expression. Returns whenTrue
if bool
is true, otherwise returns the empty string. Optionally returns whenFalse
if specified. Useful primarily in template strings.
Async
Awaitable wrappers for setTimeout
, requestAnimationFrame
and events. Takes an optional awaited f
with no arguments. If f
is provided, returns result from f
, otherwise returns undefined
. (Except for ö.waitFrames
, which calls f
every frame if everyFrame
is true
, but only returns the result of the final call.)
ö.wait( t? = 0, f?, resetPrevCall? = false ) → Promise
Waits t
milliseconds. If resetPrevCall == true
, previous pending call is rejected.
ö.nextFrame( f? ) → Promise
[browser] Waits one frame.
ö.waitFrames( n? = 1, f?, everyFrame? = false ) → Promise
[browser] Waits n
frames. If everyFrame == true
, callback is executed every frame.
ö.waitFor( selector, event, f? ) → Promise
[browser] Waits for specified event. Takes only one element, and one event type.
ö.load( url, isJSON? = true, errorMessage? = null, settings? = {} ) → Promise
[browser (Alternatively: Use node 18+)] Loads (and parses) JSON. Optionally loads HTML. Super simple fetch wrapper. On error, simply returns the error message, or optionally returns your custom error message. If you need to pass headers or other settings to the fetch call, use the settings
object.
ö.pipeAsync( v, ...funcs ) → Promise
See ö.pipe
.
Throttling
ö.throttle( f, t? = 50 ) → Function
Throttles execution of f
to one call per t
milliseconds. If called multiple times per period, the last call gets executed.
ö.debounce( f, t? = 50, immediately? = false ) → Function
Debounces execution of f
until no calls are made within t
milliseconds. If called multiple times per period, the last call gets executed. If immediately
is set to true
, the first call gets executed as well.
ö.onAnimationFrame( f ) → Function
[browser] Defers execution of f
to next animation frame. If called multiple times per frame, the last call gets executed.
Error handling and logging
All logging methods can be silenced globally by calling ö.verbose(false)
.
ö.attempt( f, handler?, ...args) → result | handled error
Wrapper around a try statement. It attempts to call f
with ...args
, and returns the result. If f
throws, it returns handler
, or the return value of handler
if handler
is a function. handler
gets the error as argument. handler
defaults to a function returning the caught error.
let tried = ö.attempt(tryThis, 'It failed', 1, 2, 3)
// or
let tried = ö.attempt(() => tryThis(1, 2, 3), 'It failed')
// or
let tried = ö.attempt(tryThis, e => ö.log(e.message), 1, 2, 3)
ö.attemptAsync( f, handler?, ...args) → result | handled error
Same, but awaits f
and handler
.
ö.verbose( isVerbose?, isThrowing? ) → { isVerbose, isThrowing }
Set isVerbose
, turns off error/message logging when set to false
. Defaults to true
. Optionally set isThrowing
to true
, in order to throw errors instead of logging them.
Returns an object containing the current state of { isThrowing, isVerbose }
.
ö.error( error, ...rest ) → console.error or thrown Error, arguments
Logs errors to console, optionally throws instead. Returns single argument, or multiple arguments as an array.
ö.warn( message, ...rest ) → console.warn, arguments
Outputs arguments to console. Returns single argument, or multiple arguments as an array.
ö.log( ...messages ) → console.log, arguments
Outputs arguments to console. Returns single argument, or multiple arguments as an array. Can be used like so: let x = ö.log( y*z );
or to tap into a call chain.
ö.time( f?, label? ) → logs time, f return value | undefined
The basic usecase is as a simple wrapper for console.time
, optionally with a label. If f
is a string, it is used as a label. In that case, the timer ends when calling ö.timeEnd
with a matching label.
Optionally, it accepts a function with no arguments, which gets timed, called and its value returned. In this case console.timeEnd
is called internally.
ö.timeEnd( label? ) → logs time
Simple wrapper for console.timeEnd
.
ö.message( str ) → 'ö says: ${str}'
Wrapper for internal messages.
Basic type checking
Less verbose than typeof
/Array.isArray
/instanceof
:
ö.isBool( v ) → Boolean
ö.isNum( v ) → Boolean
ö.isInt( v ) → Boolean
ö.isBigInt( v ) → Boolean
ö.isStr( v ) → Boolean
ö.isSym( v ) → Boolean
ö.isFunc( v ) → Boolean
ö.isArr( v ) → Boolean
ö.isNull( v ) → Boolean
ö.isDate( v ) → Boolean
ö.isMap( v ) → Boolean
ö.isSet( v ) → Boolean
ö.isRegex( v ) → Boolean
ö.isError( v ) → Boolean
ö.is( v ) / ö.isDefined( v ) → Boolean
ö.isnt( v ) / ö.isUndefined( v ) → Boolean
ö.isObj( v ) → Boolean
ö.isObj
excludes Array
, Map
, Set
, Date
and RegExp
. And null
, of course.
ö.isPlainObj( v ) → Boolean
Checks if v
is a plain object a.k.a. pojo, that is, has the same prototype as Object
.
ö.isNakedObj( v ) → Boolean
Checks if v
is a naked object, that is, has null
as prototype.
ö.isIterable( v ) → Boolean
Checks for [Symbol.iterator]
in v
.
Type conversion
ö.mapToObj( map ) → Object
Any iterable except strings work, but produce arraylike objects without a length
.
ö.objToMap( obj ) → Map
DOM and browser
ö.getLocal( item ) → Object
[browser] Gets item
from local storage, if any. Converts item to Object
via JSON.parse
.
ö.setLocal( item, v ) → v
[browser] Sets item
in local storage to v
, and returns v
.
ö.getCss( prop, selector? = ':root') → css property value
[browser] Gets prop
on selected element, or from document.documentElement
if selector
is unset, and returns v
. Mainly used for getting global --props
, using css as master for global variables.
ö.setCss( prop, v, selector? = ':root') → v
[browser] Sets prop
to v
, optionally on selected element, and returns v
.
ö.createElement( html, isSvg? = false ) → Element
[browser] Creates an Element
from an html string. Optionally creates an SVGElement
.
ö.parseDOMStringMap( o ) → Object
Parses a DOMStringMap
as JSON
. Used internally when reading from Element.dataset
.
ö.deepest( element, selector? = '*' ) → Element
[browser] Finds deepest Element
in element
, optionally matching selector
.
Random stuff
ö.rorövovarorsospoproråkoketot( str ) → String
Converts string to Rövarspråket.
Chain
Chain a.k.a TypelessScript lets you chain any method calls, on any type, kind of like a pipe on speed 🧙, or a jQuery for any object. It simply shoves the return value around, allowing you to think about more important stuff than intermediate variables.
Here's an example:
import { chain } from 'ouml/chain'
let guessWhat = chain(11)
.f(v => [...Array(v).keys()])
.map(v => v ** v)
.sum()
.toString()
.length()
.return()
It takes the number 11, makes an array of integers using the .f()
directive, maps the values to the power of themselves, sums them using an ö
method, converts the resulting number to a string, gets the length of the string, and returns it.
Here's another:
import { chainAsync } from 'ouml/chain'
let errorMessage = 'error'
let nameOfPriciestProduct = await chainAsync('https://dummyjson.com/products')
.load(true, errorMessage)
.returnIf(v => v === errorMessage)
.products()
.sort((a, b) => a.price > b.price)
.at(0)
.title()
.return()
It takes a url, loads it as json using an ö
method, handles the error case, gets the products property of the json object, sorts it, gets the first one, gets the title, and returns it. Simple as that!
Usage
chain
chains method calls, but with some quirks and gotchas. For example, properties on objects can be retrieved by calling the property name as a function. Methods on objects in the global scope can be accessed by an underscore, for example Object_groupBy()
. Also, if a method in the chain creates an error, the step is skipped by default (and the error is logged), prioritising a return value. You can override this by setting isThrowing
to true, or handle the error with a .try()
.
Use like so:
import { chain, chainAsync } from 'ouml/chain'
let processedValue = chain('AnyValueOfAnyType')
.anyMethodOnCurrentType()
.anyPropertyOnCurrentValue()
.anyMethodInÖ()
.anyMethodInGlobalScope()
.AnyObjectInGlobalScope_anyMethod()
.f(anyFunction)
.peek() // Logs current value and type
.returnIf(anyFunctionReturningABoolean)
.try(tryFunction, catchFunction)
.return()
Or like so, saving the chain for later, providing the value last:
import { chain } from 'ouml/chain'
const doStuffAndThings = chain().f(coolStuff).f(wonderfulThings).end()
let processedValue = doStuffAndThings('anyValue')
A quick note on performance: chain
does string matching, proxying and other fun stuff that adds some overhead. It adds a small hit performance-wise, and might not be the best option in a game loop 😇. It's mainly a proof of concept, but since it produces some really nice, terse and readable code, it might come in handy in some situations!
Methods
Chain exports two methods:
chain( value?, isThrowing? = false, isAsync? = false ) → Proxy
Chain wraps a value, and creates a Proxy
that handles the chaining. chain
evaluates lazily, so nothing is calculated until .return()
or .value
is called. Errors are skipped by default, set isThrowing
to true to throw errors instead. Optionally, set isAsync
to true
to handle async values, or use:
chainAsync( value, isThrowing? = false ) → Proxy
Same as chain
, but results in a Promise
.
"Methods"
The chain proxy defines a few special cases, that look and behave like methods:
.return() → value
Executes call chain, and returns computed value.
.value → value
Same as .return()
, executes call chain, and returns computed value.
() → value
A method call with no arguments has the same effect as .return()
or .value
, executes call chain, and returns computed value.
.end() → function( value ) → value
Ends the chain, and returns a function that takes a value and executes the chain on it, allowing you to save a chain as a function.
.returnIf( function ) → value | Proxy
Guard clause, lets you exit the call chain early. The function receives the current value as argument, and is expected to return a boolean. Returns current value on truthy values, otherwise continues call chain.
.try( tryFunction, catchFunction? ) → Proxy
Error handler, lets you try a function, and run catchFunction
if it throws. tryFunction
receives the current value as argument, catchFunction
receives value, error
as arguments. catchFunction
defaults to v => v
, simply passing the previous value along.
.peek() → Proxy
Lets you peek into the call chain, logging current value and type to the console.
.f( function ) → Proxy
f
allows arbitrary functions to be passed into the call chain. The function receives the current value as argument. f
is particularly useful for methods defined in a function or module scope, since these scopes are unreachable otherwise.
( function ) → Proxy
A variant for passing in arbitrary functions is directly with parentheses, in effect calling the proxy as a function, with your function as the argument. This in turn can be chained, like so:
let v = chain('Hi')(letsDo)(cool)(stuff)()
This doesn't play that nicely with Prettier, if you happen to use that, but it's cool!
.anyMethodOnCurrentType( ...args? ) → Proxy
Lets you call a method of the current value. Methods are called "as is", so for exemple a .map(v => v)
on an array takes a function, .toUpperCase()
on a string takes no argument, and .toUpperCase()
on a number is skipped along with a warning to the console, since no such method exists on a number.
.anyPropertyOnCurrentValue( newVal? ) → Proxy
Lets you access properties on the current value as a method call, for example .length()
to get the length of a string or an array. If newVal
is provided, sets the property to newVal
, and passes newVal
along the chain.
.anyMethodInÖ( ...args? ) → Proxy
Lets you pass any ö
method into the chain. The current value is passed as the first argument, so if you would normally call ö.sum(arr)
, in a chain you need only call .sum()
.
.anyMethodInGlobalScope( ...args? ) → Proxy
Lets you pass any global method into the chain. The current value is passed as the first argument, so if you would normally call fetch('http://some.url')
, in a chain you need only call .fetch()
.
.anyObjectInGlobalScope_anyMethod( ...args? ) → Proxy
Lets you pass any method on a global object into the chain. The current value is passed as the first argument, so if you would normally call JSON.parse(someString)
or Array.from(someIterable)
, in a chain you need only call .JSON_parse()
or .Array_from()
.
If you have defined any methods in the global scope that have underscores in their names, use .f(v => my_global_method(v))
instead, since underscores get parsed out by the proxy.
Öbservable
öbservable is loosely based on how vue.js handles reactivity, but it is much simpler, and, truthfully, not as good 🤪. It is, however, shockingly small, 1Kb minified.
Usage
öbservable uses Proxy
to intercept changes to observable values, and in doing so detects for exemple direct array manipulation.
Use like so:
import { observable, isObservable, observe } from 'ouml/öbservable'
let obs = observable(['a', 'b', 'c'])
let lengthObserver = observe(
() => obs.length,
v => ö.log(`The length is ${v}`),
)
let firstItemObserver = observe(
() => obs[0],
v => ö.log(`The first item is ${v}`),
)
// Logs The length is 3, The first item is a
await ö.wait(666)
obs.shift()
// Logs The length is 2, The first item is b, after 666ms
You can also use the raw observable as input to observe
, or call observe
directly on the observable (due to some Proxy
trickery):
let thisGuy = observable({ name: 'Guy', surname: 'This' })
observe(thisGuy, (val, oldVal, changedProp) =>
ö.log(`${changedProp} has changed`),
)
thisGuy.observe(v => ö.log(`Name: ${v.name} Surname: ${v.surname}`))
thisGuy.surname = 'Fawkes'
When called as a method, the getter argument to observe
is omitted.
Methods
öbservable exports three methods:
observable( value ) → observable object
Takes a value
, and returns it wrapped in an observable Proxy
, recursively wrapping nested objects as well. If you add a new property to an observable, the value of the new property is made observable as well (if it's not a primitive).
If value
is a primitive (String
, Number
, Boolean
etc), the value is wrapped in an object with a single property: value
. You cannot assign to a primitive observable value directly, you need to use the value
prop instead, or else you'd overwite the proxy.
let x = observable('foo')
observe(x, ö.log)
x = 'bar' // Won't work.
let x = observable('foo')
observe(x, ö.log)
x.value = 'bar' // Assign to value instead.
observe( getter, callback ) → observer object
Takes a getter
, responsible for reading an observable and producing a value, and a callback
that acts on the value.
The getter
can be either a raw observable, or a function returning the processed value of an observable.
The callback
receives value
, prevValue
, updatedKey
and observer
as arguments. The values passed to callback
are copied from the observable, so you can't mutate the observable value in the callback (that would create an infinite loop anyways, so don't try it 🤯).
If you're observing an object, updatedKey
can be useful in order to retrieve and act on only the property that changed. However, if you're destructuring multiple properties from a nested object, updatedKey
refers to the key local to the updated object, so in this case make sure not to use the same property name on different levels
.
observer
is a reference to the observer object, giving access to primarily the stop()
method.
If the getter is a raw primitive observable, the value is unwrapped before the callback is called, like so:
let o = observable(0)
observe(o, v => ö.log(`The value is ${v}`)) // logs 'The value is 0'
or
let o = observable(0)
o.observe(v => ö.log(`The value is ${v}`)) // logs 'The value is 0'
If the getter is a function, you need to access the value
prop, like so:
let o = observable(0)
observe(() => `The value is ${o.value}`, ö.log) // logs 'The value is 0'
It's a matter of taste, really.
When working with deep data structures, you can observe an entire object structure, and receive updates when properties on child objects change, like so:
let deep = observable({
a: { b: { c: { d: "What's the purpose of it all?" } } },
})
observe(deep, ö.log)
deep.a.b.c.d = 'Deep stuff'
The drawback with this, however, is that the entire object returned from the getter gets deep cloned every time the observer is triggered (to avoid recursion among other things). This is fairly untested with regards to performance, so try to keep the data structure fairly small. There are possible optimisations to be done here, maybe in the future...
When working with larger data structures, try to be as specific as possible in the getter. As a rule of thumb, get the values you output in the callback, nothing more. Maybe something like this:
let bigAssObservable = observable(bigAssObject)
observe(() => {
let {
stuff,
that,
we,
childObject: { really, need },
} = bigAssObservable
return { stuff, that, we, really, need }
}, renderSmallPartOfBigAssObject)
isObservable( value ) → Boolean
Checks whether a value is observable or not, just in case you'd forgotten.
Observable object
observable()
returns observables, responsible for notifying observers when their value changes. When an observable is read by an observer, the observer is added to an internal Set
of observers. These get updated when values change.
If the observable holds a primitive value, it has a value
property, otherwise values are accessed just like a regular object or array.
The observable also holds Symbol
s for observable
and primitive
, used internally, and for easier debugging.
You can also call observe
directly on an observable object (observe
is not a proper property on the object though, this is handled by the getter in the Proxy
).
Observer object
observe()
returns observers, holding the current value of the observed observable, and a few methods and properties for flow control. You don't need to save a reference to the object, but it might come in handy if you want to stop observing later on.
let x = observable(0)
let o = observe(x, ö.log)
x.value = 666 // logs 666
o.stop()
o.pause()
Pauses the observer.
o.unpause()
You'll never guess.
o.stop()
Stops the observer from receiving updates, and unsubscribes the observer from observables.
o.update()
Updates current value and calls callback if the value has changed. Called internally by the observable.
o.value
Holds the most currently returned value from the getter
. Usable mostly for debugging.
o.prevValue
Holds the previous value. Usable mostly for debugging.
o.paused
Set to true
if paused, otherwise undefined
.
o.stopped
Set to true
if stopped, otherwise undefined
.
Övents
övents is a collection of should've-been-in-the-browser-already custom events.
Usage
Övents implements the svelte/action
interface, and are usable as svelte actions, but can be used in any browser context like so:
let el = document.querySelector('#someElement')
resize(el)
// or, if you need cleanup:
let resizer = resize(el)
el.addEventListener('resize', someCallback)
// When you're done:
resizer.destroy()
Events
resize
Emit when an Element
gets resized, as observed by ResizeObserver
. Relays the ResizeObserverEntry
in the details
object.
enterview, exitview
Emit when an Element
's bounding box enters or exits the viewport.
sticktotop, sticktobottom
Emit when an Element
's bounding box touches the top/bottom of the viewport. Useful for detecting when an Element
with position: sticky
sticks to the viewport. One caveat: This works only if the sticky elements have top: 0
or bottom: 0
.
Event status is passed via a sticky
prop on the details
object.
swipe
Emits swipeleft
, swiperight
, swipeup
, swipedown
when user swipes on a touch device.
clickoutside
Emits on click or tap outside Element
.
Colour
Oklch lets you use colour in an understandable way. oklch
is great! Use oklch
!
Hsla used to be great, but ever since Css colour level 4 became the norm, there have been much better options for working with colour, so ö.hsla
and ö.toHsla
have been removed as of version 0.3.0.
And since oklch and its sibling oklab are great, there's really no need to support any other colour space for day-to-day use.
The colour
module provides simple functions for working with immutable oklch colours in js. It exports the default function colour()
, that creates Colour
objects. It also exports isColour()
.
Use like so:
import colour, { isColour } from 'ouml/colour'
let red = colour('#f00')
let blue = colour('hsl(239.96 100% 50%)')
let purple = red.mix(blue)
ö.log(`${purple}`)
// logs oklch(53.9985% 0.1337 316.0189 / 1)
ö.log(isColour(purple), isColour(purple.valueOf()))
// logs true, false
Or without intermediaries:
ö.log(`${colour('#f00').mix('hsl(239.96 100% 50%)')}`)
// logs oklch(53.9985% 0.1337 316.0189 / 1)
Or have a look at a small demo.
colour()
colour( lightness | cssString | Colour, chroma, hue, alpha ) → Colour
The colour
function creates Colour
s from either css strings in hex/rgb/rgba/hsl/hsla/oklch format, or a Colour
, or numeric values for the colour channels.
Inputs are clamped to valid values. lightness
takes values between 0 and 1, chroma
takes values between 0 and 0.4, hue
takes values between 0 and 360, and alpha
takes values between 0 and 1.
Colour methods
The methods that return Colour
are chainable, and the methods that return an array of Colour
s are chainable via .map()
.
All methods that interpolate between colours, such as .mix()
or .palette()
, interpolate through oklab
by default, since oklab avoids hue variations when interpolating. If you want a poppier feel, go for oklch
instead. Oklch and oklab are the only colourspaces supported. Try out interpolation through different colour spaces here to see why.
Colour.lightness( v? ) → Colour
Getter/setter for the lightness value. Gets the value when used without argument. Sets the value if number
is provided, or sets the value by calling v
if a function
is provided. The function gets the current lightness value as argument.
Colour.chroma( v? ) → Colour
Getter/setter for the chroma value. Works the same as .lightness()
. For example, a saturate
method might look like this:
const saturate = (clr, amount = 0.01) => clr.chroma(v => v + amount)
Colour.hue( v? ) → Colour
Getter/setter for the hue value.
Colour.alpha( v? ) → Colour
Getter/setter for the alpha value.
...Colour
Colour
objects spread nicely into arrays, in [l, c, h, a]
order.
Colour.valueOf() → { lightness, chroma, hue, alpha }
Returns an object with values. Useful for console.log
or to get all values out.
Colour.toString() → css string
Returns a css string. Useful for all sorts of colour related things. Called implicitly on string concatenation and in template strings, so this works nicely:
let red = colour('#e11')
let myDarkRedElement = `<div style="background:${red.darken()}; color:${red.lighten(0.8)}">Hello</div>`
Colour.complement() → Colour
Inverts the hue value. Nothing fancy.
Colour.invert() → Colour
Inverts lightness and hue.
Colour.darken( amount = 0.1 ) → Colour
Darkens Colour
by a percentage of amount
.
Colour.lighten( amount = 0.1 ) → Colour
Lightens Colour
by a percentage of amount
.
Colour.palette( colourspace? = 'oklab' ) → [Colours]
Returns a palette of 11 colours from light to dark, based on the current colour. Both chroma and lightness get adjusted to create a harmonious scale, so the exact original colour might not exist in the list.
Colour.gradient( clr: Colour | cssString | Colour[], type? = 'linear', rotation? = 0, position? = [0.5, 0.5], colourspace? = 'oklab' ) → css gradient string
A simple wrapper around css gradient strings, letting you create dynamic gradients easily.
clr
can be either a css string, a Colour
, or an array of Colour
s. The current color is included at the start of the gradient.
Supports a subset of gradient options. Works for 'linear'
, 'radial'
and 'conic'
gradients. position
has no effect on linear gradients, and rotation
has no effect on radial gradients. There's no support for positional values for colours, all colours are added linearly. For fancier gradients, roll your own!
A simple gradient from blackish to whiteish:
let gradient = colour('#111').gradient('#eee')
// returns 'linear-gradient(in oklab 0deg, oklch(17.7638% 0 180 / 1), oklch(94.9119% 0 180 / 1))'
Colour.steps( clr: Colour | cssString, steps? = 1, colourspace? = 'oklab', interpolator? = ö.lerp ) → [Colours]
Interpolates between current colour and colour
, in steps
, and returns an array of Colour
s. The start and end values are included in the array, so if steps
is 1, the resulting array has three colours.
Lets you do for example:
let html = `<div style="display:flex">${colour('hsl(42.41 100% 56%)')
.steps('rgb(255, 33, 74)', 10)
.map(v => `<div style="height:5rem; flex:1 0; background:${v}"></div>`)
.join('')}</div>`
Colour.mix( clr: Colour | cssString, percent? = 0.5, colourspace? = 'oklab', interpolator? = ö.lerp ) → Colour
Blends two colours together, basically. Use it like this, for example:
let html = ö.map(
'Fancy effect:',
(v, i, a) =>
`<span style="color: ${colour('#000').mix(
'#FE5C03',
100 - (100 / a.length) * i,
)}">${v}</span>`,
)
Colour.getInterpolator( clr: Colour | cssString, colourspace? = 'oklab', interpolator? = ö.lerp ) → function( t ) → Colour
Creates an interpolator function that takes a t
value between 0 and 1, and returns the Colour
at t
between current colour and colour
.