sassfp v1.6.1

SassFP

v1.6.1

A set of utilities inspired by Ramda, lodash FP, and other Functional libraries for Sass.

Like Ramda, all the functions in SassFP are iteratee-first, data-last. Some native Sass methods have been re-supplied here with that argument order, but, so far, only those that I've personally needed in projects.

Installation

SassFP is a node-module and can be installed via

npm install sassfp

Requirements

SassFP requires Sass 3.3 or greater due to its reliance on and ability to manipulate Sass maps. As of v1.3.1, it is compatible with Sass 3.5.

• String Methods
  • prefixStr
  • suffixStr
  • explode
  • pathToMap
• List Methods
  • implode
  • repeat
  • slice
  • head
  • tail
  • init
  • last
  • flatten
  • partition
  • contains
  • intersection
  • difference
• Functional Methods
  • always
  • identity
  • T
  • F
  • map
  • map-with-index
  • filter
  • reject
  • reduce
  • pipe
  • compose
  • cond
• Object Methods
  • path
  • prop
  • pathOr
  • propOr
  • assign
  • pick
  • omit
  • listPaths
• Mathematical Methods
  • add
  • multiply
  • subtract
  • divide
  • percent
  • double
  • square
  • inc
  • dec
  • sum
  • power
  • to-decimal-places
• Misc Methods
  • applyUnit
  • px
  • em
  • vw
  • vh
  • rem
• Argument-converted Sass Functions
  • fpAppend
  • fpJoin
  • fpNth
• Convenience Type Boolean Methods
  • is_list
  • is_color
  • is_string
  • is_boolean
  • is_number
  • is_null
  • is_map
  • isnt_list
  • isnt_color
  • isnt_string
  • isnt_boolean
  • isnt_number
  • isnt_null
  • isnt_map
• Relational Methods
  • equals
  • eq
  • lt
  • lte
  • gt
  • gte

String Methods

prefixStr

($prefix, $str)

Returns $str prefixed with $prefix.

prefixStr('selector', 'one'); // => 'selectorone'

suffixStr

($suffix, $str)

Returns $str with $suffix appended to it.

suffixStr('selector', 'one'); // => 'oneselector'

explode

($separator, $str)

Converts a string to a list by splitting on $separator.

explode('-', 'selector-one'); // => ('selector', 'one')

pathToMap

($path, $val)

Converts a dot-delimited string and any value into a Sass map with that same object heirarchy.

pathToMap('x', 10px); => (x: 10px)
pathToMap('x.y', 10px); => (x: (y: 10px))
pathToMap('x.y.z', 10px); => (x: (y: (z: 10px)))

List Methods

implode

($glue: '', $list: ())

Returns a string where all the members of $list have been concatenated together with $glue between them.

implode('-', ('selector', 'one')); // => 'selector-one'

repeat

($times, $item)

Returns a list where $item is represented $times times

repeat(3, 10); // => (10, 10, 10)

slice

($start, $end, $list)

Returns $list's members beginning at position $start and ending at $end.

slice(3, 5, ('alex', 'billy', 'charlie', 'dani', 'elliot')); // => ('charlie', 'dani', 'elliot')

head

($list)

Returns the first member of $list.

head(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'alex'

tail

($list)

Returns all but the first member of $list.

tail(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'billy' 'charlie' 'dani' 'elliot'

init

($list)

Returns all but the last member of $list.

init(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'alex' 'billy' 'charlie' 'dani'

last

($list)

Returns the last member of $list.

last(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'elliot'

flatten

($list...)

Returns a flattened version of $list.

flatten(#fff, red, (#222, #333)); // => (#fff, red, #222, #333)

partition

($predicate, $list)

Returns 2-dimensional list where the first member contains all the members of $list for which $predicate is true, and the second, all those for which it is false.

partition(gt5, (4,5,6,7)); // => ((6 7), (4 5))
partition(gt5, (0,1,2,3)); // => ((), (0 1 2 3))
partition(gt5, (6,7,8,9)); // => ((6 7 8 9), ())

contains

($item, $list)

Returns a Boolean whether $item is in $list.

$strlist: ('alex' 'billy' 'charlie' 'dani' 'elliot');
contains('alex', $strlist); => true
contains('allen', $strlist); => false
contains('billy', $strlist); => true

intersection

($list1, $list2)

Returns a new list of what both $list1 and $list2 have in common. Inverse of difference.

$strlist: ('alex' 'billy' 'charlie' 'dani' 'elliot');
intersection(('alex', 'billy', 'allen'), $strlist); // // => ('alex' 'billy')
intersection(('alex.a', 'billy', 'allen'), $strlist); // // => ('billy')
intersection(('alex.a', 'allen'), $strlist); // // => ()

difference

($list1, $list2)

Returns new list of what $list1 and $list2 do not have in common. Inverse of intersection.

$strlist: ('alex' 'billy' 'charlie' 'dani' 'elliot');
difference(('alex' 'billy'), $strlist); // => ()
difference(('alex' 'billy' 'allen'), $strlist); // => ('allen')
difference(('alex.a' 'billy' 'allen'), $strlist); // => ('alex.a' 'allen')

Functional Methods

always

($val,$b)

Returns the first value passed to it. As of v1.5.0, this accepts a second optional parameter, $b, to not only better align with Ramda's signature, but to also allow it to participate in compositional flows. identity ought to be substituted for any previous usage of always, though there are no plans to deprecate the single-argument functionality.

always(1)  // => 1
always('asdf')  // => "asdf"
always(('x', 'y', 'z'))  // => ("x", "y", "z")
always('x', 'y')  // => "x"
always(true, false)  // => true
always(false, true)  // => false

identity

($val)

Returns the value passed to it.

identity(1)  // => 1
identity('asdf')  // => "asdf"
identity(('x', 'y', 'z'))  // => ("x", "y", "z")
identity(true)  // => true
identity(false)  // => false

T

($val...)

Returns true, regardless of what arguments are passed or how many there are.

T(1)  // => true
T('asdf')  // => true
T(('x', 'y', 'z'))  // => true
T('x', 'y', 'z')  // => true
T(true)  // => true
T(false)  // => true
T()  // => true

F

($val...)

Returns false, regardless of what arguments are passed or how many there are.

F(1)  // => false
F('asdf')  // => false
F(('x', 'y', 'z'))  // => false
F('x', 'y', 'z')  // => false
F(true)  // => false
F(false)  // => false
F()  // => false

map

($fn, $list)

Returns a new list where each member of $list has had function $fn run against it.

@function darkenbyten($color) {
  @return darken($color, 10%);
}
map(darkenbyten, (#fff, red, #222, #333)); // => #e6e6e6 #cc0000 #090909 #1a1a1a

As of v1.2.0, $fn may itself be a list where the first member is the function to be run against each member of $list, and the others are extra arguments that the function would require, in effect allowing functions to be decorated.

@function darkenby($pct, $color) {
  @return darken($color, $pct);
}
map((darkenby, 10%), (#fff, red, #222, #333)); // => #e6e6e6 #cc0000 #090909 #1a1a1a

Because Sass supports space-separated lists, the commas are optional, and omitting them may increase legibility.

map((darkenby 10%), (#fff, red, #222, #333)); // => #e6e6e6 #cc0000 #090909 #1a1a1a

Most important, however, is that the value(s) provided by iterating over $list must always be in the last argument position $fn expects.

map-with-index

($fn, $list)

Returns a new list where each member of $list has had function $fn run against it and its index as two arguments. Works identically to map, but with the item's index passed as an additional argument to $fn in the last argument position and the value provided by $list in the second-to-last.

map-with-index(prefixStr, ("alex", "billy", "charlie")); // => ("alex1", "billy2", "charlie3")
map-with-index(add, (4, 5, 6)); // => (5, 7, 9)

filter

($predicate, $list)

Returns a new list where $predicate returns true for members of $list. Inverse of reject.

@function gt5($val) {
  @return $val > 5;
}
filter(gt5, (4,5,6,7)); // => (6, 7)

reject

($predicate, $list)

Returns a new list where $predicate returns false for members of $list. Inverse of filter.

reject(gt5, (4,5,6,7)); // => (4, 5)

reduce

($fn, $initial, $list)

Accumulates the result of running each member of $list through $fn starting with the $initial value and $list's first member.

reduce(prefixStr, '.', ('alex', 'billy', 'charlie')); // => ".alexbillycharlie"
reduce(suffixStr, '', ('alex', 'billy', 'charlie')); // => "charliebillyalex"
reduce(add, 0, (4,5,6)); // => 15

As of v1.4.0, $fn may itself be a list where the first member is the function to be run against each member of $list, and the others are extra arguments that the function would require, in effect allowing functions to be decorated.

reduce((sum, 1, 2), 0 (4, 5, 6)); // => 24

Most important, however, is that the value(s) provided by iterating over $list must always be in the last argument position $fn expects and the accumulator in the second-to-last. So, in the example above, the execution goes like this:

  function  add'l values  accumulator   member    outcome
     ⬇︎       ⬇︎   ⬇︎           ⬇︎         ⬇︎         ⬇︎
    sum(      1,   2,          0,         4 )   =>   7
    sum(      1,   2,          7,         5 )   =>   15
    sum(      1,   2,          15,        6 )   =>   24

In the particular case of sum, argument order isn't important, but for others it could very well be.

pipe

($params...)

Accepts a list of arguments where the last item is the initial data and the others are a sequence of functions to run. Returns the result of each of the functions being run on the successive results from first to last. The very last item must be the data being operated on. Functions being passed in with additional parameters take the form of sub-lists.

pipe(
  flatten,
  (map, darkenbyten),
  (#fff, red, (#222, #333))
); // => #e6e6e6 #cc0000 #090909 #1a1a1a

compose

($params...)

Same as pipe, but functions run in reverse order. Initial data remains last argument.

compose(
  unquote,
  (prefixStr, '.'),
  (implode, '-'),
  (join, ('d', 'e')),
  ('a', 'b', 'c')
); // => .d-e-a-b-c

compose(
  double,
  (reduce, add, 0),
  (map, square),
  (4,5,6)
); // => 154

cond

(($predicates-and-actions-list, $data))

Accepts a two dimensional list of predicate and transformation functions that, taken together, are read as a series of nested if / else statements, where the first true value encountered has its transformation executed against the supplied data. Like pipe and compose, the data comes in the last position.

The assumption of both the predicate and transformation functions is that they are unary functions where the provided data serves as the parameter to both functions. Alternatively, n-ary functions may also be used in either assuming that the passed value is coming in the functions' last argument positions, and all other arguments are provided by as a list.

To ensure a return, use the T function in the last position of predicate-transformation pairs (so, second-to-last in overall list), coupled with an always. As noted with map, omitting commas in the inner lists may help with legibility.

@function darkenby($pct, $color) { @return darken($color, $pct); }
@function lightenby($pct, $color) { @return lighten($color, $pct); }

cond((
  ((equals yellow), (lightenby 20))
  ((equals red), (darkenby 10))
  (T, (always #000))
  red
)) // => #cc0000

Object Methods

path

($key-list, $map)

Allows for getting at nested attributes in a Sass map using list syntax. Ensures a null return for any unrecognized paths.

$colors: (header:(one: #333, two: #444), footer: #666);
path(('header', 'two'), $colors); // => #444
path(('footer'), $colors); // => #666
path(('header', 'two', 'three', 'four'), $colors); // => null

prop

($path, $map)

Allows for getting at nested attributes in a Sass map using dot syntax. Ensures a null return for any unrecognized paths.

$colors: (header:(one: #333, two: #444), footer: #666);
prop('header.two', $colors); // => #444
prop('footer', $colors); // => #666
prop('body', $colors); // => null

pathOr

($fallback, $key-list, $map)

Returns the value of a path lookup when successful, and returns a provided fallback when not.

$colors: (header:(one: #333, two: #444), footer: #666);
pathOr(':(', ('header', 'two'), $colors); // => #444
pathOr(':(', ('body'), $colors); // => ':('
pathOr(':(', ('header', 'two', 'three', 'four'), $colors); // => ':('

propOr

($fallback, $path, $map)

Returns the value of a prop lookup when successful, and returns a provided fallback when not.

$colors: (header:(one: #333, two: #444), footer: #666);
propOr(':(', 'header.two', $colors); // => #444
propOr(':(', 'footer', $colors); // => #666
propOr(':(', 'body', $colors); // => ':('

assign

($map1, $map2)

Merges 2 deeply-nested map objects.

$colors: (header:(one: #333, two: #444), footer: #666);
assign($colors, (header: (one: red))); // => (header:(one: red, two: #444), footer: #666)
assign($colors, (header: (three: red))); // => (header:(one: #333, two: #444, three: red), footer: #666)

pick

($key-list, $map)

Creates new map object from $map selecting keys provided by $key-list.

$colors: (header:(one: #333, two: #444), footer: #666);
pick('footer', $colors); // => (footer: #666)
pick('header.one', $colors); // => (header:(one: #333))
pick(('header', 'footer'), $colors); // same as original

omit

($key-list, $map)

Creates new map object from the provided one, then removing a specified list of keys.

omit(
  ('header.one', 'header.three.four'),
  (header: (
    one: #333,
    two: #444,
    three: (
      four: red,
      five: blue
    )
  ),
  footer: #666
));
// =>
//   (header: (
//     two: #444,
//     three: (
//       five: blue
//     )
//   ),
//   footer: #666
// )

listPaths

($map)

Creates a flat, dot-delimited list of all the paths of $map.

$colors: (header:(one: #333, two: #444), footer: #666);
listPaths($colors); // => ("header" "header.one" "header.two" "footer")

Mathematical Methods

add

($x, $y)

Adds $y to $x.

add(10, 2); // => 12

multiply

($x, $y)

Multiplies $x by $y.

multiply(10, 2); // => 20

subtract

($x, $y)

Subtracts $y from $x.

subtract(10, 2); // => 8

divide

($x, $y)

Divides $x by $y.

divide(10, 2); // => 5

percent

($x, $y)

Returns $x's percent of $y.

percent(2, 10); // => 50%

double

($x)

Doubles $x.

double(10); // => 20

square

($x)

Squares $x.

square(10); // => 100

inc

($x)

Increments $x.

inc(10); // => 11

dec

($x)

Decrements $x.

dec(10); // => 9

sum

($num-list...)

Accepts a list of numbers and returns the sum of them.

sum(10, 5, 2); // => 17

power

($exponent: 1, $num: 1)

Returns the total after multiplying $num $exponent times.

power(2, 10); // => 100 (10^2)
power(10, 2); // => 1024 (2^10)

to-decimal-places

($digits: 2, $num: 1)

Returns $num to $digits number of significant digits dropping anything beyond it. $digits is 2 by default since Sass has a default of returning 3 significant digits.

to-decimal-places(2, 10.129); // => 10.12

Misc Methods

applyUnit

($unit, $val)

Appends $unit to $val.

applyUnit(px, 50); // => 50px
applyUnit(em, 50); // => 50em

px

($val)

Shortcut function to apply px unit.

px(50); // => 50px

em

($val)

Shortcut function to apply em unit.

em(50); // => 50em

vw

($val)

Shortcut function to apply vw unit.

vw(50); // => 50vw

vh

($val)

Shortcut function to apply vh unit.

vh(50); // => 50vh

rem

($val)

Shortcut function to apply rem unit.

rem(50); // => 50rem

Argument-converted Sass Functions

Existing Sass functions with data-last argument orders.

fpAppend

($item, $list)

Adds an item to the end of a provided list. See Sass append documentation.

fpAppend('charlie', ('alex', 'billy')); // => 'alex' 'billy' 'charlie'

fpJoin

($list2, $list1)

Joins $list2 to the end of $list1. See Sass join documentation.

fpJoin(('charlie' 'dani'), ('alex', 'billy')); // => 'alex' 'billy' 'charlie' 'dani'

fpNth

($position, $list)

Returns the item at $position from $list. See Sass nth documentation.

fpNth(2, ('alex', 'billy')); // => 'billy'

Convenience Type Boolean Methods

is_list

($val)

Returns whether $val is a list.

is_list((#fff, red, #222, #333)); // => true
is_list(#fff red #222 #333); // => true
is_list(#fff); // => false

is_color

($val)

Returns whether $val is a color.

is_color(red); // => true
is_color('red'); // => false

is_string

($val)

Returns whether $val is a string.

is_string('val'); // => true
is_string(false); // => false

is_boolean

($val)

Returns whether $val is a boolean.

is_boolean(false); // => true
is_boolean('val'); // => false

is_number

($val)

Returns whether $val is a number.

is_number(10); // => true
is_number('10'); // => false

is_null

($val)

Returns whether $val is a null.

is_null(null); // => true
is_null(true); // => false

is_map

($val)

Returns whether $val is a map.

is_map((header: red)); // => true
is_map((header red)); // => false

isnt_list

($val)

Returns whether $val is not a list.

isnt_list((#fff, red, #222, #333)); // => false
isnt_list(#fff red #222 #333); // => false
isnt_list(#fff); // => true

isnt_color

($val)

Returns whether $val is not a color.

isnt_color(red); // => false
isnt_color('red'); // => true

isnt_string

($val)

Returns whether $val is not a string.

isnt_string('val'); // => false
isnt_string(false); // => true

isnt_boolean

($val)

Returns whether $val is not a boolean.

isnt_boolean(false); // => false
isnt_boolean('val'); // => true

isnt_number

($val)

Returns whether $val is not a number.

isnt_number(10); // => false
isnt_number('10'); // => true

isnt_null

($val)

Returns whether $val is not a null.

isnt_null(null); // => false
isnt_null(true); // => true

isnt_map

($val)

Returns whether $val is not a map.

isnt_map((header: red)); // => false
isnt_map((header red)); // => true

Relational

equals

($a, $b)

Returns whether $a and $b are equivalent (function version of Sass == operator).

equals(1, 1); // => true
equals(1, '1'); // => false
equals((header: red), (header: red)); // => true
equals((header red), (header red)); // => true

eq

($a, $b)

Returns whether $a and $b are equivalent (alias of equals).

lt

($a, $b)

Returns whether the first argument is less than the second (function version of Sass < operator).

lt(1, 10) // => true
lt(10, 1) // => false
lt(1, 1) // => false

lte

($a, $b)

Returns whether the first argument is less than or equal to the second (function version of Sass <= operator).

lte(1, 10) // => true
lte(10, 1) // => false
lte(1, 1) // => true

gt

($a, $b)

Returns whether the first argument is greater than the second (function version of Sass > operator).

gt(1, 10) // => false
gt(10, 1) // => true
gt(1, 1) // => false

gte

($a, $b)

Returns whether the first argument is greater than or equal to the second (function version of Sass >= operator).

gte(1, 10) // => false
gte(10, 1) // => true
gte(1, 1) // => true