Skip to content

feat(stdlib): add @acton/json decoder module#1097

Open
zakrad wants to merge 1 commit into
ton-blockchain:masterfrom
zakrad:feat/json-stdlib
Open

feat(stdlib): add @acton/json decoder module#1097
zakrad wants to merge 1 commit into
ton-blockchain:masterfrom
zakrad:feat/json-stdlib

Conversation

@zakrad

@zakrad zakrad commented May 22, 2026

Copy link
Copy Markdown

Summary

Adds a small, read-only JSON decoder to the Acton stdlib as @acton/json. It is
the natural companion to fs.readFile, which can load a JSON file as a string
but offers no way to parse it.

Implements the proposal in #1096.

API

Values are addressed with a JSON Pointer (RFC 6901), e.g. /token/decimals or
/items/0:

fun json.getInt(src: string, path: string): int?
fun json.getString(src: string, path: string): string?
fun json.getBool(src: string, path: string): bool?
fun json.exists(src: string, path: string): bool
val src = fs.readFile("fixtures/jetton-metadata.json");
if (src != null) {
    val decimals = json.getInt(src!, "/decimals") ?? 9;
    val name = json.getString(src!, "/name") ?? "unknown";
    val mintable = json.getBool(src!, "/mintable") ?? false;
}

Design

  • Lookup semantics mirror @acton/env: invalid JSON, a missing path, or a
    type mismatch all return null, so ?? can supply a default.
  • JSON Pointer paths via serde_json's built-in Value::pointer() — no
    custom path parser.
  • getInt accepts a JSON integer, or a JSON string holding a decimal/0x-hex
    integer. Floats return null. Bare numbers beyond 64 bits are not reliably
    representable, so they return null rather than a lossy value; encode such
    values as JSON strings to carry full 257-bit integers losslessly.
  • getBool distinguishes a present false (returned as false) from an
    absent/non-boolean value (null).

Implementation

  • Host handlers in src/ffi/json.rs (EXTCALL ids 300303), registered in
    src/ffi/mod.rs, following the existing env/fs pattern.
  • Tolk surface in lib/json.tolk.
  • Reuses serde_json, already a dependency; no new crates.

Testing

  • New integration tests in
    tests/integration/test_runner/json_reads_typed_values_by_pointer_tests.rs
    cover numbers/strings/hex/floats, nested paths, array indices, present-false
    vs null, missing paths, and invalid JSON.
  • Verified locally: just fmt-check, cargo clippy --workspace --all-targets --all-features -- -D warnings, typos, acton docgen --check, acton fmt --check, acton check, and acton test (native stdlib suite).

Docs

Generated docs/content/docs/standard_library/json.mdx and the overview index
via acton docgen; docgen --check passes.

Closes #1096

Note

Prepared with the help of an AI coding assistant; reviewed and locally verified by the author before submission.

Adds a small read-only JSON decoder to the Acton stdlib, complementing
fs.readFile (which loads a JSON file as a string but cannot parse it).

Values are addressed with a JSON Pointer (RFC 6901). getInt/getString/
getBool return null on invalid JSON, a missing path, or a type mismatch
(consistent with @acton/env); exists reports whether a pointer resolves.
getInt also accepts quoted decimal/0x-hex strings to carry full 257-bit
integers losslessly.

Host handlers (EXTCALL ids 300-303) are added under src/ffi/json.rs and
registered in src/ffi/mod.rs; the Tolk surface is in lib/json.tolk.

Closes ton-blockchain#1096
@zakrad
zakrad requested review from Shvandre and i582 as code owners May 22, 2026 23:13
@netlify

netlify Bot commented May 22, 2026

Copy link
Copy Markdown

Deploy Preview for acton-staging ready!

Name Link
🔨 Latest commit 6630656
🔍 Latest deploy log https://app.netlify.com/projects/acton-staging/deploys/6a10e338415161000800b799
😎 Deploy Preview https://deploy-preview-1097--acton-staging.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions github-actions Bot added documentation Improvements or additions to documentation stdlib Tasks about Acton standard library labels May 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation stdlib Tasks about Acton standard library

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose a JSON codec in the Tolk stdlib (typed accessors over fs.readFile)

1 participant