From d93e083206a36c8c444d5591c60c7b33554d4e76 Mon Sep 17 00:00:00 2001 From: David Chambers Date: Sat, 26 May 2018 11:10:08 +0200 Subject: [PATCH] Version 1.0.0 --- README.md | 206 +++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 2 +- 2 files changed, 207 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ffb0480 --- /dev/null +++ b/README.md @@ -0,0 +1,206 @@ +Fantasy Land + +# sanctuary-identity + +Identity is the simplest container type: a value of type `Identity a` +always contains exactly one value, of type `a`. + +`Identity a` satisfies the following [Fantasy Land][] specifications: + +```javascript +> const Useless = require ('sanctuary-useless') + +> S.map (k => k + ' '.repeat (16 - k.length) + +. (Z[k].test (Identity (Useless)) ? '\u2705 ' : +. Z[k].test (Identity (['foo'])) ? '\u2705 * ' : +. /* otherwise */ '\u274C ')) +. (S.keys (Z.filter ($.test ([]) ($.TypeClass), Z))) +[ 'Setoid ✅ * ', // if ‘a’ satisfies Setoid +. 'Ord ✅ * ', // if ‘a’ satisfies Ord +. 'Semigroupoid ❌ ', +. 'Category ❌ ', +. 'Semigroup ✅ * ', // if ‘a’ satisfies Semigroup +. 'Monoid ❌ ', +. 'Group ❌ ', +. 'Filterable ❌ ', +. 'Functor ✅ ', +. 'Bifunctor ❌ ', +. 'Profunctor ❌ ', +. 'Apply ✅ ', +. 'Applicative ✅ ', +. 'Chain ✅ ', +. 'ChainRec ✅ ', +. 'Monad ✅ ', +. 'Alt ❌ ', +. 'Plus ❌ ', +. 'Alternative ❌ ', +. 'Foldable ✅ ', +. 'Traversable ✅ ', +. 'Extend ✅ ', +. 'Comonad ✅ ', +. 'Contravariant ❌ ' ] +``` + +#### `Identity :: a -⁠> Identity a` + +Identity's sole data constructor. Additionally, it serves as the +Identity [type representative][]. + +```javascript +> Identity (42) +Identity (42) +``` + +#### `Identity.@@type :: String` + +Identity [type identifier][]. + +```javascript +> type (Identity (42)) +'sanctuary-identity/Identity@1' + +> type.parse (type (Identity (42))) +{namespace: 'sanctuary-identity', name: 'Identity', version: 1} +``` + +#### `Identity.fantasy-land/of :: a -⁠> Identity a` + +`of (Identity) (x)` is equivalent to `Identity (x)`. + +```javascript +> S.of (Identity) (42) +Identity (42) +``` + +#### `Identity.fantasy-land/chainRec :: ((a -⁠> c, b -⁠> c, a) -⁠> Identity c, a) -⁠> Identity b` + +```javascript +> Z.chainRec ( +. Identity, +. (next, done, x) => Identity (x >= 0 ? done (x * x) : next (x + 1)), +. 8 +. ) +Identity (64) + +> Z.chainRec ( +. Identity, +. (next, done, x) => Identity (x >= 0 ? done (x * x) : next (x + 1)), +. -8 +. ) +Identity (0) +``` + +#### `Identity#@@show :: Showable a => Identity a ~> () -⁠> String` + +`show (Identity (x))` is equivalent to `'Identity (' + show (x) + ')'`. + +```javascript +> show (Identity (['foo', 'bar', 'baz'])) +'Identity (["foo", "bar", "baz"])' +``` + +#### `Identity#fantasy-land/equals :: Setoid a => Identity a ~> Identity a -⁠> Boolean` + +`Identity (x)` is equal to `Identity (y)` [iff][] `x` is equal to `y` +according to [`Z.equals`][]. + +```javascript +> S.equals (Identity ([1, 2, 3])) (Identity ([1, 2, 3])) +true + +> S.equals (Identity ([1, 2, 3])) (Identity ([3, 2, 1])) +false +``` + +#### `Identity#fantasy-land/lte :: Ord a => Identity a ~> Identity a -⁠> Boolean` + +`Identity (x)` is less than or equal to `Identity (y)` [iff][] `x` is +less than or equal to `y` according to [`Z.lte`][]. + +```javascript +> S.filter (S.lte (Identity (1))) +. ([Identity (0), Identity (1), Identity (2)]) +[Identity (0), Identity (1)] +``` + +#### `Identity#fantasy-land/concat :: Semigroup a => Identity a ~> Identity a -⁠> Identity a` + +`concat (Identity (x)) (Identity (y))` is equivalent to +`Identity (concat (x) (y))`. + +```javascript +> S.concat (Identity ([1, 2, 3])) (Identity ([4, 5, 6])) +Identity ([1, 2, 3, 4, 5, 6]) +``` + +#### `Identity#fantasy-land/map :: Identity a ~> (a -⁠> b) -⁠> Identity b` + +`map (f) (Identity (x))` is equivalent to `Identity (f (x))`. + +```javascript +> S.map (Math.sqrt) (Identity (64)) +Identity (8) +``` + +#### `Identity#fantasy-land/ap :: Identity a ~> Identity (a -⁠> b) -⁠> Identity b` + +`ap (Identity (f)) (Identity (x))` is equivalent to `Identity (f (x))`. + +```javascript +> S.ap (Identity (Math.sqrt)) (Identity (64)) +Identity (8) +``` + +#### `Identity#fantasy-land/chain :: Identity a ~> (a -⁠> Identity b) -⁠> Identity b` + +`chain (f) (Identity (x))` is equivalent to `f (x)`. + +```javascript +> S.chain (n => Identity (n + 1)) (Identity (99)) +Identity (100) +``` + +#### `Identity#fantasy-land/reduce :: Identity a ~> ((b, a) -⁠> b, b) -⁠> b` + +`reduce (f) (x) (Identity (y))` is equivalent to `f (x) (y)`. + +```javascript +> S.reduce (S.concat) ([1, 2, 3]) (Identity ([4, 5, 6])) +[1, 2, 3, 4, 5, 6] +``` + +#### `Identity#fantasy-land/traverse :: Applicative f => Identity a ~> (TypeRep f, a -⁠> f b) -⁠> f (Identity b)` + +`traverse (_) (f) (Identity (x))` is equivalent to +`map (Identity) (f (x))`. + +```javascript +> S.traverse (Array) (x => [x + 1, x + 2, x + 3]) (Identity (100)) +[Identity (101), Identity (102), Identity (103)] +``` + +#### `Identity#fantasy-land/extend :: Identity a ~> (Identity a -⁠> b) -⁠> Identity b` + +`extend (f) (Identity (x))` is equivalent to +`Identity (f (Identity (x)))`. + +```javascript +> S.extend (S.reduce (S.add) (1)) (Identity (99)) +Identity (100) +``` + +#### `Identity#fantasy-land/extract :: Identity a ~> () -⁠> a` + +`extract (Identity (x))` is equivalent to `x`. + +```javascript +> S.extract (Identity (42)) +42 +``` + +[Fantasy Land]: https://github.com/fantasyland/fantasy-land/tree/v3.5.0 +[`Z.equals`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v9.0.0#equals +[`Z.lte`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v9.0.0#lte +[iff]: https://en.wikipedia.org/wiki/If_and_only_if +[type identifier]: https://github.com/sanctuary-js/sanctuary-type-identifiers/tree/v2.0.1 +[type representative]: https://github.com/fantasyland/fantasy-land/tree/v3.5.0#type-representatives diff --git a/package.json b/package.json index a9cb4a2..86bb3ec 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sanctuary-identity", - "version": "0.0.0", + "version": "1.0.0", "description": "Fantasy Land -compliant Identity type", "license": "MIT", "repository": {