JairusSW / json-as

╦╔═╗╔═╗╔╗╔ ╔═╗╔═╗ ║╚═╗║ ║║║║══╠═╣╚═╗ ╚╝╚═╝╚═╝╝╚╝ ╩ ╩╚═╝ Table of Contents • Installation • Usage • Examples • Omitting Fields • Using Nullable Primitives • Working with Unknown or Dynamic Data • Using Raw JSON Strings • Working with Enums • Using Custom Serializers or Deserializers • Performance • Comparison to JavaScript • Performance Tuning • Running Benchmarks Locally • Debugging • Architecture • Contributing • Who uses it? • License • Contact Installation Add the to your command (e.g. in package.json) Optionally, for additional performance, also add: Alternatively, add it to your If you'd like to see the code that the transform generates, run the build step with Usage Examples Omitting Fields This library allows selective omission of fields during serialization using the following decorators: **@omit** This decorator excludes a field from serialization entirely. **@omitnull** This decorator omits a field only if its value is null. **@omitif((self: this) => condition)** This decorator omits a field based on a custom predicate function. If age were higher than 18, it would be included in the serialization. Using nullable primitives AssemblyScript doesn't support using nullable primitive types, so instead, json-as offers the class to remedy it. For example, this schema won't compile in AssemblyScript: Instead, use to allow nullable primitives: Working with unknown or dynamic data Sometimes it's necessary to work with unknown data or data with dynamic types. Because AssemblyScript is a statically-typed language, that typically isn't allowed, so json-as provides the and types. Here's a few examples: **Working with multi-type arrays** When dealing with arrays that have multiple types within them, eg. , use **Working with unknown objects** When dealing with an object with an unknown structure, use the type **Working with dynamic types within a schema** More often, objects will be completely statically typed except for one or two values. In such cases, can be used to handle fields that may hold different types at runtime. **Working with nullable primitives and dynamic data** Using Raw JSON strings Sometimes its necessary to simply copy a string instead of serializing it. For example, the following data would typically be serialized as: If, instead, one wanted to insert Raw JSON into an existing schema/data structure, they could make use of the JSON.Raw type to do so: Working with enums By default, enums with values other than arn't supported by AssemblyScript. However, you can use a workaround: Using custom serializers or deserializers This library supports custom serialization and deserialization methods, which can be defined using the and decorators. Here's an example of creating a custom data type called which serializes to The serializer function converts a instance into a string format . The deserializer function parses the string back into a instance. These functions are then wrapped before being consumed by the json-as library: This allows custom serialization while maintaining a generic interface for the library to access. Performance The library is engineered for **multi-GB/s processing speeds**, leveraging SIMD and SWAR optimizations along with highly efficient transformations. The charts below highlight key performance metrics such as build time, operations-per-second, and throughput. Comparison to JavaScript The following charts compare JSON-AS (both SWAR and SIMD variants) against JavaScript's native implementation. The published charts are generated locally and pushed to the branch. > Note: Benchmarks reflect the **latest version**. Older versions may show different performance. > > Current local benchmark machine: AMD Ryzen 7 7800X3D (8 cores, 8 threads), 96 MB L3 cache, 32 GB RAM. > > Benchmark results include normal end-to-end work such as allocating the destination object or array before deserializing into it. Raw parser throughput is higher than the published figures because these numbers intentionally include that allocation/setup cost. Performance Tuning Instead of using flags for setting options, is configured by environmental variables. Here's a short list: **JSON_CACHE** (default: 0) - Enables caching costly strings based on hit frequency. May boost string serialization in excess of 22 GB/s. **JSON_DEBUG** (default: 0) - Sets the debug level. May be within range **JSON_MODE** (default: SWAR) - Selects which mode should be used. Can be . Note that may be required. **JSON_USE_FAST_PATH** (default: 0) - When set to , the transform emits the fast implementation for generated structs. When unset or , it emits only the slow path. **JSON_WRITE** (default: "") - Select a series of files to output after transform and optimization passes have completed for easy inspection. Usage: Running Benchmarks Locally Benchmarks are run directly on top of for tighter control over the engine configuration. • Install the local benchmark prerequisites: • Add to your and make sure is installed: • Install project dependencies: • Run either benchmark suite directly: • Build charts from the latest local logs: • Publish benchmark charts to the branch: If you already have fresh logs and only want to rebuild charts and push them: Or run the full local publish flow in one step: Debugging • Prints out generated code at compile-time • The above and prints keys/values as they are deserialized • Writes out generated code to for easy inspection Architecture For a deep dive into how json-as works internally, including the transform system, optimization modes (NAIVE, SWAR, SIMD), and buffer management, see ARCHITECTURE.md. Contributing We welcome contributions! Please see CONTRIBUTING.md for guidelines on: • Setting up your development environment • Running tests and benchmarks • Code style and commit conventions • The pull request process Who uses it? A few companies and open-source projects use json-as! | Company/Project | Description…