@kaiko.io/rescript-deser 7.0.0-alpha.2 → 8.0.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased] - 8.0.0-alpha.1
+
+### Added
+
+- **BREAKING**: `Deserializer` module type now requires `toJSON` and `isSafeCast`
+  - `toJSON` serializes values back to `JSON.t`
+  - `isSafeCast` returns true if the deserialized type has identical runtime representation
+    to `JSON.t` (allowing `Obj.magic` optimization in `toJSON`)
+
+- `MakeDeserializer` implements `toJSON` and `isSafeCast` automatically:
+  - `isSafeCast` returns true for primitive types (`String`, `Int`, `Float`, `Boolean`, `Literal`)
+  - `isSafeCast` returns false for `Date`/`Datetime` (runtime representation differs from JSON string)
+  - When `isSafeCast()` is true, `toJSON` uses `Obj.magic` for zero-cost serialization
+  - When false, `toJSON` recursively serializes each field
+
+  **Caveats:**
+  - `Any` is considered safe, assuming the user only uses it when the ReScript type matches the
+    `JSON.t` representation. Misuse (e.g., declaring `Any` for a transformed type) will cause
+    `toJSON` to produce incorrect output.  This matches the usage of `Any` in `fromJSON`.
+
+  - `Morphism(inner, fn)` only checks if `inner` is safe, ignoring the transformation. If `fn`
+    changes the runtime representation (e.g., `Morphism(String, parseInt)`), `toJSON` will serialize
+    the transformed value as if it were the original type, producing incorrect potentially incorrect
+    `JSON.t`.
+
+
+## [7.0.0] - 2025-12-19
+
+### Changed
+
+- **BREAKING**: Migrate to ReScript 12
+- **BREAKING**: Use the new `dict<_>` shortcut syntax
+
+## [7.0.0-alpha.2] - 2025-12-19
+
+### Changed
+
+- CI: Use the frozen yarn.lock
+- CI: Refactor CI pipeline
+
+## [7.0.0-alpha.1] - 2025-11-18
+
+### Changed
+
+- Migrate from `Js.Json` to `RescriptCore.JSON` API
+- Add automated test infrastructure for CLI and CI
+
+## [6.0.1] - 2025-06-01
+
+### Fixed
+
+- Fix leaking the `Result.t` on Collections
+
+## [6.0.0] - 2025-06-01
+
+### Changed
+
+- **BREAKING**: Rename module to `Deser` to avoid clash with RescriptCore's JSON
+- Remove dependency on `rescript-prelude`
+
+## [5.0.1] - 2024-11-05
+
+### Changed
+
+- Use 'esmodule' output format
+
+## [5.0.0] - 2024-11-05
+
+### Changed
+
+- **BREAKING**: Require ReScript >= 11.1.0
+
+## [4.0.2] - 2024-04-27
+
+### Changed
+
+- Allow to compile with ReScript 11.1
+
+## [4.0.1] - 2024-01-27
+
+### Changed
+
+- Require compatible versions of prelude and rescript
+
+## [4.0.0] - 2024-01-11
+
+### Changed
+
+- **BREAKING**: Upgrade to ReScript 11
+- Switch to `rescript.json` configuration file
+- Add explicit `@@uncurried` to the module
+
+## [3.3.0] - 2023-12-15
+
+### Changed
+
+- Update to Prelude 6.5.0
+
+## [3.2.0] - 2023-10-16
+
+### Changed
+
+- Update to Prelude 6.3.0
+
+## [3.1.3] - 2023-07-03
+
+### Fixed
+
+- Add missing `bsconfig.json`
+
+## [3.1.2] - 2023-07-03
+
+### Changed
+
+- Compile with both es6 and commonjs
+
+## [3.1.1] - 2023-07-03
+
+### Changed
+
+- Distribute the compiled JS files
+
+## [3.1.0] - 2023-05-12
+
+### Added
+
+- Add `Literal` field type
+
+## [3.0.0] - 2023-04-28
+
+### Changed
+
+- **BREAKING**: Update to latest Prelude and ReScript
+
+## [2.1.0] - 2023-01-23
+
+### Added
+
+- Add support for recursive structs with `Field.Self`
+- Add trivial infinite recursion detection via `checkFieldsSanity`
+- Add QUnit tests
+
+## [2.0.0] - 2022-12-07
+
+### Changed
+
+- **BREAKING**: Switch to `MakeDeserializer` functor pattern
+
+## [1.0.1] - 2022-12-07
+
+### Changed
+
+- Improve the README
+
+## [1.0.0] - 2022-12-07
+
+### Added
+
+- Initial release as `@kaiko.io/rescript-deser`

package/lib/bs/.compiler.log

@@ -1,2 +1,2 @@
-#Start(1766178477130)
-#Done(1766178477131)
+#Start(1769849605835)
+#Done(1769849605836)

package/lib/bs/compiler-info.json

@@ -4,5 +4,5 @@
   "bsc_hash": "a2b93197b8c05fc70981fe131a9ed75f8462a9f615f71055f306c9deb058d3cf",
   "rescript_config_hash": "6e13fe97e162573c9ab73327567294583b34d549775f8391e1d5c8ccc0c5d580",
   "runtime_path": "/home/manu/src/kaiko/rescript-deser/node_modules/@rescript/runtime",
-  "generated_at": "1766178477132"
+  "generated_at": "1769849605837"
 }

package/lib/bs/src/Deser.res

@@ -25,7 +25,9 @@ module type Deserializer = {
   type t
   let name: string
   let fromJSON: JSON.t => result<t, string>
+  let toJSON: t => JSON.t
   let checkFieldsSanity: unit => result<unit, string>
+  let isSafeCast: unit => bool
 }
 
 module Field = {
@@ -305,6 +307,66 @@ module Field = {
       )
       ->Result.map(_ => ())
     }
+
+  let rec isSafeCast = (field: t): bool =>
+    switch field {
+    // Any is considered *safe* because it SHOULD only be used if the type you're getting from
+    // JSON.t is compatible with the internal representation anyways.
+    | Any => true
+    | String | Literal(_) | Int | Float | Boolean | Self => true
+    | Date | Datetime => false
+    | Morphism(inner, _) => isSafeCast(inner)
+    | Array(inner)
+    | Optional(inner)
+    | OptionalWithDefault(inner, _)
+    | Mapping(inner)
+    | DefaultWhenInvalid(inner, _) =>
+      isSafeCast(inner)
+    | Tuple(fields) => fields->Array.every(isSafeCast)
+    | Object(fields) => fields->Array.every(((_, f)) => isSafeCast(f))
+    | Deserializer(mod) | Collection(mod) => {
+        module M = unpack(mod: Deserializer)
+        M.isSafeCast()
+      }
+    }
+
+  let rec serialize: ('a, t, t) => JSON.t = (value, shape, self) =>
+    switch shape {
+    | Any | String | Int | Float | Boolean => value->Obj.magic
+    | Literal(v) => JSON.String(v)
+    | Self => serialize(value, self, self)
+    | Date | Datetime => JSON.String(value->Obj.magic->Date.toISOString)
+
+    | Morphism(inner, _) => serialize(value, inner, self)
+    | Array(inner) => JSON.Array(value->Obj.magic->Array.map(v => serialize(v, inner, self)))
+
+    | Tuple(fields) =>
+      JSON.Array(Belt.Array.zipBy(value->Obj.magic, fields, (v, f) => serialize(v, f, self)))
+
+    | Object(fields) =>
+      JSON.Object(
+        fields
+        ->Array.filterMap(((key, fieldType)) =>
+          value
+          ->Obj.magic
+          ->Dict.get(key)
+          ->Option.map(fieldValue => (key, serialize(fieldValue, fieldType, self)))
+        )
+        ->Dict.fromArray,
+      )
+    | Optional(inner) =>
+      switch value->Obj.magic {
+      | Some(v) => serialize(v, inner, self)
+      | None => JSON.Null
+      }
+    | OptionalWithDefault(inner, _) | DefaultWhenInvalid(inner, _) => serialize(value, inner, self)
+    | Mapping(inner) =>
+      JSON.Object(value->Obj.magic->Dict.mapValues(v => serialize(v, inner, self)))
+    | Deserializer(mod) | Collection(mod) => {
+        module M = unpack(mod: Deserializer)
+        M.toJSON(value->Obj.magic)
+      }
+    }
 }
 
 module type Serializable = {
@@ -315,10 +377,24 @@ module type 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)))
+  let (loc, _f) = __LOC_OF__(module(S: Serializable))
   let name = `Deserializer ${__MODULE__}, ${loc}`
 
-  %%private(external _toNativeType: FieldValue.t => t = "%identity")
+  external _toNativeType: FieldValue.t => t = "%identity"
+  external _fromNativeType: t => FieldValue.t = "%identity"
+
+  let safeCastCache: ref<option<bool>> = ref(None)
+
+  let isSafeCast = () => {
+    switch safeCastCache.contents {
+    | Some(cached) => cached
+    | None => {
+        let result = Field.isSafeCast(fields)
+        safeCastCache := Some(result)
+        result
+      }
+    }
+  }
 
   @doc("Checks for trivial infinite-recursion in the fields of the module.
 
@@ -331,11 +407,20 @@ module MakeDeserializer = (S: Serializable): (Deserializer with type t = S.t) =>
   ")
   let checkFieldsSanity = () => Field.checkFieldsSanity(name, fields, false)
 
-  @doc("Parse a `'a` into `result<t, string>`")
+  @doc("Parse a `JSON.t` into `result<t, string>`")
   let fromJSON: JSON.t => result<t, _> = json => {
     switch json->Field.fromUntagged(fields, fields) {
     | res => Ok(res->_toNativeType)
     | exception TypeError(e) => Error(e)
     }
   }
+
+  @doc("Serialize a `t` into `JSON.t`")
+  let toJSON: t => JSON.t = value => {
+    if isSafeCast() {
+      value->Obj.magic
+    } else {
+      Field.serialize(value, fields, fields)
+    }
+  }
 }

package/lib/bs/tests/index.res

@@ -4,7 +4,7 @@ module Appointment = {
   type t = {
     note: string,
     date: Date.t,
-    extra: option<string>,
+    extra?: string,
   }
   module Deserializer = Deser.MakeDeserializer({
     type t = t
@@ -14,15 +14,42 @@ module Appointment = {
   })
 }
 
+module List = {
+  type rec t = {
+    head: string,
+    tail?: t,
+  }
+  module Deserializer = Deser.MakeDeserializer({
+    type t = t
+    open Deser.Field
+    let fields = Object([("head", String), ("tail", Optional(Self))])
+  })
+}
+
+module Ledger = {
+  type rec t = {
+    records: List.t,
+    next?: t,
+  }
+  module Deserializer = Deser.MakeDeserializer({
+    type t = t
+    open Deser.Field
+    let fields = Object([
+      ("records", Deserializer(module(List.Deserializer))),
+      ("next", Optional(Self)),
+    ])
+  })
+}
+
 module_("Basic deserializer", _ => {
   let valid: array<(_, Appointment.t)> = [
     (
       %raw(`{"note": "Bicentennial doctor's appointment", "date": "2100-01-01"}`),
       {
-        note: "Bicentennial doctor's appointment",
-        date: Date.fromString("2100-01-01"),
-        extra: None,
-      },
+        "note": "Bicentennial doctor's appointment",
+        "date": Date.fromString("2100-01-01"),
+        "extra": None, // Deser always return `undefined` for missing, optional fields
+      }->Obj.magic,
     ),
     (
       %raw(`{
@@ -33,7 +60,7 @@ module_("Basic deserializer", _ => {
       {
         note: "Bicentennial doctor's appointment",
         date: Date.fromString("2100-01-01"),
-        extra: Some("Don't take your stop-aging pills the night before the appointment"),
+        extra: "Don't take your stop-aging pills the night before the appointment",
       },
     ),
   ]
@@ -131,15 +158,8 @@ module_("Recursive deserializer", _ => {
   })
 
   test("Finite list", qunit => {
-    module List = Deser.MakeDeserializer({
-      open Deser.Field
-
-      type t
-      let fields = Object([("head", String), ("tail", Optional(Self))])
-    })
-
     qunit->expect(1)
-    qunit->deepEqual(List.checkFieldsSanity(), Ok(), "Ok")
+    qunit->deepEqual(List.Deserializer.checkFieldsSanity(), Ok(), "Ok")
   })
 
   test("Correctly deserializes recursive data", qunit => {
@@ -156,34 +176,21 @@ module_("Recursive deserializer", _ => {
   })
 
   test("Recursion in sub-deserializer", qunit => {
-    module List = Deser.MakeDeserializer({
-      open Deser.Field
-
-      type t
-      let fields = Object([("head", String), ("tail", Optional(Self))])
-    })
-
-    module Ledger = Deser.MakeDeserializer({
-      open Deser.Field
-
-      type t
-      let fields = Object([("records", Deserializer(module(List))), ("next", Optional(Self))])
-    })
-
     let data = %raw(`
        {"records": {"head": "A", "tail": {"head": "B"}},
         "next": {"records": {"head": "A", "tail": {"head": "B"}}}}
     `)
-    let expected = {
+    // Deser always returns `undefined` for missing optional fields
+    let expected: Ledger.t = {
       "records": {"head": "A", "tail": {"head": "B", "tail": None}},
       "next": {
         "records": {"head": "A", "tail": {"head": "B", "tail": None}},
         "next": None,
       },
-    }
+    }->Obj.magic
 
     qunit->expect(1)
-    qunit->deepEqual(data->Ledger.fromJSON->Obj.magic, Ok(expected), "nice ledger")
+    qunit->deepEqual(data->Ledger.Deserializer.fromJSON, Ok(expected), "nice ledger")
   })
 })
 
@@ -210,3 +217,141 @@ module_("Type safety limits", _ => {
     )
   })
 })
+
+module_("isSafeCast and toJSON", _ => {
+  module SafePrimitives = {
+    type t = {
+      name: string,
+      count: int,
+      ratio: float,
+      active: bool,
+    }
+    module Deserializer = Deser.MakeDeserializer({
+      type t = t
+      open Deser.Field
+      let fields = Object([("name", String), ("count", Int), ("ratio", Float), ("active", Boolean)])
+    })
+  }
+
+  module SafeNested = {
+    type t = {
+      items: array<string>,
+      tags: dict<int>,
+      label?: string,
+    }
+    module Deserializer = Deser.MakeDeserializer({
+      type t = t
+      open Deser.Field
+      let fields = Object([
+        ("items", Array(String)),
+        ("tags", Mapping(Int)),
+        ("label", Optional(String)),
+      ])
+    })
+  }
+
+  module UnsafeWithDate = {
+    type t = {
+      name: string,
+      created: Date.t,
+    }
+    module Deserializer = Deser.MakeDeserializer({
+      type t = t
+      open Deser.Field
+      let fields = Object([("name", String), ("created", Date)])
+    })
+  }
+
+  module NestedUnsafe = {
+    type t = {event: UnsafeWithDate.t}
+    module Deserializer = Deser.MakeDeserializer({
+      type t = t
+      open Deser.Field
+      let fields = Object([("event", Deserializer(module(UnsafeWithDate.Deserializer)))])
+    })
+  }
+
+  test("Safe types: primitives return true for isSafeCast", qunit => {
+    qunit->expect(1)
+    qunit->isTrue(SafePrimitives.Deserializer.isSafeCast(), "primitives are safe")
+  })
+
+  test("Safe types: nested arrays/mappings/optionals return true for isSafeCast", qunit => {
+    qunit->expect(1)
+    qunit->isTrue(SafeNested.Deserializer.isSafeCast(), "nested safe types are safe")
+  })
+
+  test("Unsafe types: Date returns false for isSafeCast", qunit => {
+    qunit->expect(1)
+    qunit->isFalse(UnsafeWithDate.Deserializer.isSafeCast(), "Date is unsafe")
+  })
+
+  test("Unsafe types: nested deserializer with Date returns false", qunit => {
+    qunit->expect(1)
+    qunit->isFalse(NestedUnsafe.Deserializer.isSafeCast(), "nested unsafe is unsafe")
+  })
+
+  test("Round-trip for safe types", qunit => {
+    let json: JSON.t = %raw(`{"name": "test", "count": 42, "ratio": 3.14, "active": true}`)
+    switch SafePrimitives.Deserializer.fromJSON(json) {
+    | Ok(value) => {
+        let serialized = SafePrimitives.Deserializer.toJSON(value)
+        qunit->deepEqual(serialized, json, "round-trip preserves data")
+      }
+    | Error(msg) => qunit->isFalse(true, msg)
+    }
+  })
+
+  test("Round-trip for unsafe types with Date", qunit => {
+    let json: JSON.t = %raw(`{"name": "event", "created": "2024-01-15T10:30:00.000Z"}`)
+    switch UnsafeWithDate.Deserializer.fromJSON(json) {
+    | Ok(value) => {
+        let serialized = UnsafeWithDate.Deserializer.toJSON(value)
+        qunit->deepEqual(serialized, json, "round-trip preserves data with Date")
+      }
+    | Error(msg) => qunit->isFalse(true, msg)
+    }
+  })
+
+  test("Nested deserializer safety propagation", qunit => {
+    let json: JSON.t = %raw(`{"event": {"name": "meeting", "created": "2024-06-01T09:00:00.000Z"}}`)
+    switch NestedUnsafe.Deserializer.fromJSON(json) {
+    | Ok(value) => {
+        let serialized = NestedUnsafe.Deserializer.toJSON(value)
+        qunit->deepEqual(serialized, json, "nested unsafe round-trip works")
+      }
+    | Error(msg) => qunit->isFalse(true, msg)
+    }
+  })
+
+  test("Morphism of safe type is safe", qunit => {
+    module WithMorphism = Deser.MakeDeserializer({
+      type t = int
+      open Deser.Field
+      let fields = Morphism(Int, v => v)
+    })
+    qunit->expect(1)
+    qunit->isTrue(WithMorphism.isSafeCast(), "morphism of Int is safe")
+  })
+
+  test("List deserializer is safe (recursive with Self)", qunit => {
+    qunit->expect(1)
+    qunit->isTrue(List.Deserializer.isSafeCast(), "recursive list with strings is safe")
+  })
+
+  test("Appointment deserializer is unsafe (has Date)", qunit => {
+    qunit->expect(1)
+    qunit->isFalse(Appointment.Deserializer.isSafeCast(), "Appointment with Date is unsafe")
+  })
+
+  test("toJSON serializes Date to ISO string", qunit => {
+    let appointment: Appointment.t = {
+      note: "Test",
+      date: Date.fromString("2024-03-15T14:30:00.000Z"),
+      extra: "extra info",
+    }
+    let json = Appointment.Deserializer.toJSON(appointment)
+    let expected: JSON.t = %raw(`{"note": "Test", "date": "2024-03-15T14:30:00.000Z", "extra": "extra info"}`)
+    qunit->deepEqual(json, expected, "Date serialized to ISO string")
+  })
+})