@kaiko.io/rescript-deser 1.0.0 → 2.0.0

package/Makefile

@@ -9,7 +9,10 @@ compile: yarn.lock
 format: yarn.lock
 	rescript format -all
 
-.PHONY: compile format
+publish: compile
+	yarn publish --access public
+
+.PHONY: format compile publish
 
 RESCRIPT_FILES := $(shell find src -type f -name '*.res')
 

package/README.md

@@ -25,7 +25,7 @@ module MyData = {
     }
 }
 
-module MyDataDeserializer = JSON.Deserializer({
+module MyDataDeserializer = JSON.MakeDeserializer({
     type t = MyData.t
     open JSON.Field
 
@@ -36,7 +36,84 @@ module MyDataDeserializer = JSON.Deserializer({
 })
 ```
 
-This creates a function `MyDataDeserializer.fromJSON` with 
+The resultant module has type:
+
+```rescript
+module type Deserializer = {
+  type t
+  let name: string
+  let fromJSON: Js.Json.t => result<t, string>
+}
+```
+
+The input module must have the module type:
+
+```rescript
+module type Serializable = {
+  type t
+  let fields: Field.t
+}
+```
+
+
+### List of variants for `Field.t`.
+
+- `String`, parses a JSON string into a ReScript `string`.
+
+- `Int`, parses a JSON number into a ReScript `int`
+
+- `Float`, parses a JSON number into a ReScript `float`
+
+- `Boolean`
+
+- `Any`, *unsafe type* to allow anything.  The result is the same underlying
+  JS representation of the object that comes from the JSON data.
+
+- `Date`, parses either a string representation of a date (datetime) or a
+  floating point representation of date (datetime) into `Js.Date.t`; we make
+  sure the result is valid and won't return NaN afterwards.
+  
+  This basically calls, `Js.Date.fromString` or `Js.Date.fromFloat`; and tests
+  the resulting value.
+  
+  `Datetime` is an alias for `Date`.
+  
+- `Optional(Field.t)`, allow the field to be missing from the JSON data in
+  which case, return `None`; if the field is present and valid return
+  `Some(value)`.
+  
+- `OptionalWithDefault(Field.t, FieldValue.t)`; same as optional but return a
+  default value instead.  Notice, this is unsafe if the actual type of the
+  default value does not match the expected type.
+  
+- `Tuple(array<Field.t>)`, parses a JSON list with an exact number of items of
+  varying types.
+
+- `Object(array<(string, Field.t)>)`, parses a JSON object that should have
+  exactly the fields described; missing items are not allowed unless they are
+  `Optional`, `OptionalWithDefault`.
+  
+- `Mapping(Field.t)`, parses a JSON object with unknown keys (of type string)
+  and a given type of value.  Valid values have the internal type
+  `Prelude.Dict.t`.
+  
+- `Deserializer(module(Deserializer))`, parses an JSON object with the function
+  `fromJSON` of another deserializer.  This allows the composition of
+  deserializers.
+  
+- `Collection(module(Deserializer))`, parses a list of items with the function
+  `fromJSON` of another deserializer.  Invalid items are ignored.  
+  
+  This is basically a shortcut to
+  `Array(DefaultWhenInvalid(Optional(Deserializer(module(M))),
+  FieldValue.null))`, with the additional post-processing to remove `None`
+  values.
+  
+- `DefaultWhenInvalid(Field.t, FieldValue.t)`, if the JSON contains an invalid
+  value, use a default instead.
+
+- `Array(Field.t)`, parses a JSON list with homogeneous items.
+
 
 ## Current limitations with recursive data
 

package/bsconfig.json

@@ -1,9 +1,13 @@
 {
-  "name": "rescript-deser",
+  "name": "@kaiko.io/rescript-deser",
   "sources": [
     {
       "dir": "src/",
       "subdirs": true
+    },
+    {
+      "dir": "tests",
+      "type": "dev"
     }
   ],
   "suffix": ".js",

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@kaiko.io/rescript-deser",
-  "version": "1.0.0",
+  "version": "2.0.0",
+  "keywords": [
+    "json",
+    "deserializer",
+    "rescript"
+  ],
   "description": "Simple JSON deserializer for ReScript",
-  "repository": "https://gitlab.com/kaiko-systems/bs-deser.git",
+  "repository": "https://gitlab.com/kaiko-systems/rescript-deser",
   "author": "Kaiko Systems <info@kaikosystems.com>",
   "license": "MIT",
   "private": false,

package/src/JSON.res

@@ -23,7 +23,7 @@ module FieldValue = {
 exception TypeError(string)
 
 @doc("The module type of a built deserializer which is suitable to add as a subparser.")
-module type BuiltDeserializer = {
+module type Deserializer = {
   type t
   let name: string
   let fromJSON: Js.Json.t => result<t, string>
@@ -54,13 +54,13 @@ module Field = {
     /// expected entries.
     | Mapping(t)
 
-    | Deserializer(module(BuiltDeserializer))
+    | Deserializer(module(Deserializer))
 
     /// A specialized Array of deserialized items that ignores unparsable
     /// items and returns the valid collection.  This saves the user from
     /// writing 'Array(DefaultWhenInvalid(Optional(Deserializer(module(M)))))'
     /// and then post-process the list of items with 'Array.keepSome'
-    | Collection(module(BuiltDeserializer))
+    | Collection(module(Deserializer))
     | DefaultWhenInvalid(t, FieldValue.t)
 
     // FIXME: this is used to add additional restrictions like variadictInt or
@@ -105,7 +105,7 @@ module Field = {
     | Datetime
     | Date => "Date"
     | Collection(m) => {
-        module M = unpack(m: BuiltDeserializer)
+        module M = unpack(m: Deserializer)
         "Collection of " ++ M.name
       }
 
@@ -122,7 +122,7 @@ module Field = {
     | Mapping(t) => `Mapping of ${t->toString}`
     | Morphism(t, _) => t->toString ++ " to apply a morphism"
     | Deserializer(m) => {
-        module M = unpack(m: BuiltDeserializer)
+        module M = unpack(m: Deserializer)
         M.name
       }
 
@@ -216,7 +216,7 @@ module Field = {
     | (Morphism(shape, f), _) => untagged->fromUntagged(shape)->f->FieldValue.any
 
     | (Collection(m), Js.Json.JSONArray(items)) => {
-        module M = unpack(m: BuiltDeserializer)
+        module M = unpack(m: Deserializer)
         items
         ->Array.map(M.fromJSON)
         ->Array.map(Result.warn)
@@ -226,7 +226,7 @@ module Field = {
       }
 
     | (Deserializer(m), _) => {
-        module M = unpack(m: BuiltDeserializer)
+        module M = unpack(m: Deserializer)
         switch untagged->M.fromJSON {
         | Ok(res) => res->FieldValue.any
         | Error(msg) => raise(TypeError(msg))
@@ -253,7 +253,7 @@ module type Serializable = {
   let fields: Field.t
 }
 
-module Deserializer = (S: Serializable) => {
+module MakeDeserializer = (S: Serializable): (Deserializer with type t = S.t) => {
   type t = S.t
   let fields = S.fields
   %%private(let (loc, _f) = __LOC_OF__(module(S: Serializable)))
@@ -269,24 +269,3 @@ module Deserializer = (S: Serializable) => {
     }
   }
 }
-
-module Test = {
-  type appointment = {
-    note: string,
-    date: Js.Date.t,
-  }
-  module Appointment = Deserializer({
-    type t = appointment
-    open Field
-
-    let fields = Object([("note", String), ("date", Date)])
-  })
-
-  type foo = array<appointment>
-  module Foo = Deserializer({
-    type t = foo
-    open Field
-
-    let fields = DefaultWhenInvalid(Array(Deserializer(module(Appointment))), []->FieldValue.array)
-  })
-}

package/tests/compile.res

@@ -0,0 +1,22 @@
+open JSON
+
+module Test = {
+  type appointment = {
+    note: string,
+    date: Js.Date.t,
+  }
+  module Appointment = MakeDeserializer({
+    type t = appointment
+    open JSON.Field
+
+    let fields = Object([("note", String), ("date", Date)])
+  })
+
+  type foo = array<appointment>
+  module Foo = MakeDeserializer({
+    type t = foo
+    open JSON.Field
+
+    let fields = DefaultWhenInvalid(Array(Deserializer(module(Appointment))), []->FieldValue.array)
+  })
+}