Commit gmsg v1.0.0

Author: HeroesLament

.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: test
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: erlef/setup-beam@v1
+        with:
+          otp-version: "27.1.2"
+          gleam-version: "1.11.1"
+          rebar3-version: "3"
+          # elixir-version: "1"
+      - run: gleam deps download
+      - run: gleam test
+      - run: gleam format --check src test

.gitignore

@@ -0,0 +1,4 @@
+*.beam
+*.ez
+/build
+erl_crash.dump

README.md

@@ -3,22 +3,34 @@
 [![Package Version](https://img.shields.io/hexpm/v/gmsg)](https://hex.pm/packages/gmsg)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gmsg/)
 
+> MessagePack encoding/decoding for Gleam.
+
+## Install
 ```sh
 gleam add gmsg@1
 ```
+
+## Quick start
 ```gleam
 import gmsg
+import gleam/io
 
-pub fn main() -> Nil {
-  // TODO: An example of the project in use
-}
+let data = gmsg.pack_string("hello")
+let Ok(bin) = gmsg.to_bit_array(data)
+io.println(bit_array.inspect(bin))
+
+// returns Dynamic
+let Ok(dynamic) =
+  gmsg.parse(bin, using: decode.string)
 ```
 
 Further documentation can be found at <https://hexdocs.pm/gmsg>.
 
 ## Development
 
 ```sh
-gleam run   # Run the project
 gleam test  # Run the tests
 ```
+
+## License
+Apache-2.0 © HeroesLament

docs/DOGMA.md

@@ -0,0 +1,16 @@
+# DOGMA — Design Principles of `gmsg`
+
+1. **Single pair of public entry-points.**  
+   `encode(msg_pack)` turns a `MsgPack` value into a `BitArray`; `parse(bits, using decoder)` turns a `BitArray` back into a typed value via a `dynamic.Decoder`.
+
+2. **Three-layer architecture.**  
+   *Wire format* ↔︎ **`MsgPack` IR** ↔︎ **`dynamic.Dynamic`** ↔︎ *your domain type*; the middle two layers mirror Gleam’s JSON codec so one decoder can serve all formats.
+
+3. **Deterministic output.**  
+   Integers are big-endian, lengths are canonical, and arrays/maps preserve caller order, guaranteeing byte-stable hashes and signatures.
+
+4. **Offset-aware streaming.**  
+   The parser returns `(value, next_bit)` tuples internally, letting higher-level helpers walk large documents without copying.
+
+5. **Backend agnostic.**  
+   Pure Gleam: works unchanged on Erlang or JavaScript, needs no NIFs, and allocates minimally.

docs/EXAMPLES.md

@@ -0,0 +1,65 @@
+# gmsg examples — direct MsgPack IR
+
+Below are three short Gleam snippets that build `MsgPack` values by hand, pass them to `gmsg.encode/1`, and (optionally) round-trip with `decode_msgpack_from_bit_offset/2`.  
+All of them avoid the **dynamic** layer so you can see the raw IR helpers in action.
+
+---
+
+## 1 · Single user record (map)
+
+```gleam
+import gmsg
+import gleam/bit_array.{inspect}
+
+let user =
+  gmsg.map(
+    from: [#("id", 42), #("name", "Ada"), #("active", True)],
+    of: gmsg.pack_string,
+    and: fn
+      Int(i) -> gmsg.pack_int(i)
+      String(s) -> gmsg.pack_string(s)
+      Bool(b) -> gmsg.pack_bool(b)
+      _ -> gmsg.pack_nil()
+  )
+
+let Ok(bin) = gmsg.to_bit_array(user)
+inspect(bin) |> io.println
+```
+
+## 2 · List of users
+```
+import gmsg
+
+let users =
+  gmsg.array(
+    from: [
+      gmsg.map(
+        from: [#("id", 1), #("name", "Ada")],
+        of: gmsg.pack_string,
+        and: gmsg.pack_int
+      ),
+      gmsg.map(
+        from: [#("id", 2), #("name", "Grace")],
+        of: gmsg.pack_string,
+        and: gmsg.pack_int
+      )
+    ],
+    of: fn(x) { x } // elements already MsgPack
+  )
+
+let Ok(payload) = gmsg.to_bit_array(users)
+```
+
+## 3 · Round-trip sanity check
+```
+import gmsg
+import gleam/result
+
+let original = gmsg.pack_string("hello, MsgPack!")
+let Ok(bits) = gmsg.to_bit_array(original)
+
+case gmsg.decode_msgpack_from_bit_offset(bits, 0) {
+  Ok(#(value, _)) -> assert value == original
+  Error(e) -> io.println("decode error: " <> e)
+}
+```

gleam.toml

@@ -0,0 +1,13 @@
+name = "gmsg"
+version = "1.0.0"
+
+description = "MessagePack encoding/decoding for Gleam."
+licences = ["Apache-2.0"]
+repository = { type = "github", user = "HeroesLament", repo = "gmsg" }
+links = [{ title = "Website", href = "" }]
+
+[dependencies]
+gleam_stdlib = ">= 0.61.0 and < 2.0.0"
+
+[dev-dependencies]
+gleeunit = ">= 1.0.0 and < 2.0.0"

manifest.toml

@@ -0,0 +1,11 @@
+# This file was generated by Gleam
+# You typically do not need to edit this file
+
+packages = [
+  { name = "gleam_stdlib", version = "0.61.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "3DC407D6EDA98FCE089150C11F3AD892B6F4C3CA77C87A97BAE8D5AB5E41F331" },
+  { name = "gleeunit", version = "1.6.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "63022D81C12C17B7F1A60E029964E830A4CBD846BBC6740004FC1F1031AE0326" },
+]
+
+[requirements]
+gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }
+gleeunit = { version = ">= 1.0.0 and < 2.0.0" }