# `nupp.serde.native` The native codec saves values as a compact binary frame on a native LuaJIT host. See [Serialization bindings](../../../../learn/runtime/data/serde/index.html#native-persistence) for what a frame preserves. ```nupp local serde = require("nupp.serde") local native = require("nupp.serde.native") local record Save level: integer inventory: {string} end local saves = serde.binding(Save) local bytes = native.encode(saves, new Save(level = 12, inventory = {"key"})) local restored = native.decode(saves, bytes) assert(restored.level == 12 and restored.inventory[1] == "key") ``` The frame keeps everything a `nupp.serde.Writer` can say: exact 64-bit integers, float widths, decimals, bytes, timestamps, and document boundaries. Members are stored by name, so a binding can gain optional fields and still read older frames. A frame holds a finite tree of values. It does not preserve shared identity or cycles, never runs code from its input, and cannot hold process handles. Its input is bounded at 16 MiB, 128 levels of nesting, and a million values. The frame is versioned and a reader rejects any version it does not know. It is specific to LuaJIT: this module raises on other hosts before it selects a binding. Use `nupp.serde.json` for data that leaves the machine. ## Types ### `Codec` _interface_ ```nupp interface Codec ... ``` A native codec with its own cache of what it selected for each binding. #### Members | Name | Kind | Description | | --- | --- | --- | | [`encode`](#nupp.serde.native.Codec.encode) | method | Encodes a value. | | [`decode`](#nupp.serde.native.Codec.decode) | method | Decodes a value. | | [`encodeDocument`](#nupp.serde.native.Codec.encodeDocument) | method | Encodes a document's contents. | | [`decodeDocument`](#nupp.serde.native.Codec.decodeDocument) | method | Decodes document contents. | | [`clear`](#nupp.serde.native.Codec.clear) | method | Forgets every binding's selections. | | [`cachedBindings`](#nupp.serde.native.Codec.cachedBindings) | method | Returns how many bindings have selections retained. | #### `encode` _method_ ```nupp encode: function(self, binding: core.Binding, borrows value: T): string ``` Encodes a value. See [`encode`](#nupp.serde.native.encode). ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `binding` | `core.Binding\` | | | `borrows value` | `T` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decode` _method_ ```nupp decode: function(self, binding: core.Binding, bytes: string): T ``` Decodes a value. See [`decode`](#nupp.serde.native.decode). ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `binding` | `core.Binding\` | | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `T` | | #### `encodeDocument` _method_ ```nupp encodeDocument: function(self, adapter: core.DocumentAdapter, borrows value: D): string ``` Encodes a document's contents. See [`encodeDocument`](#nupp.serde.native.encodeDocument). ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `adapter` | `core.DocumentAdapter\` | | | `borrows value` | `D` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeDocument` _method_ ```nupp decodeDocument: function(self, adapter: core.DocumentAdapter, bytes: string): D ``` Decodes document contents. See [`decodeDocument`](#nupp.serde.native.decodeDocument). ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `adapter` | `core.DocumentAdapter\` | | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `D` | | #### `clear` _method_ ```nupp clear: function(self): nil ``` Forgets every binding's selections. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `cachedBindings` _method_ ```nupp cachedBindings: function(self): integer ``` Returns how many bindings have selections retained. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | ## Functions ### `codec` _function_ ```nupp function codec(capacity: integer?): Codec ``` Makes a [`Codec`](#nupp.serde.native.Codec). #### Arguments | Name | Type | Description | | --- | --- | --- | | `capacity` | `integer?` | the most bindings to retain selections for; nil is 256 | #### Returns | Type | Description | | --- | --- | | `Codec` | the codec | #### Raises | Type | Condition | | --- | --- | | `string` | when the host is not native LuaJIT, or capacity is not a positive integer | ### `decode` _function_ ```nupp function decode(binding: core.Binding, bytes: string): T ``` Decodes a frame into a value. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `binding` | `core.Binding\` | the binding to construct through | | `bytes` | `string` | the frame | #### Returns | Type | Description | | --- | --- | | `T` | the value | #### Raises | Type | Condition | | --- | --- | | `nupp.serde.Error` | when the frame is malformed, of an unknown version, or does not fit the binding | ### `decodeDocument` _function_ ```nupp function decodeDocument(adapter: core.DocumentAdapter, bytes: string): D ``` Decodes a frame as document contents. #### Type parameters | Name | Description | | --- | --- | | `D` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `adapter` | `core.DocumentAdapter\` | the document adapter, such as `nupp.serde.document.adapter` | | `bytes` | `string` | the frame | #### Returns | Type | Description | | --- | --- | | `D` | the document | #### Raises | Type | Condition | | --- | --- | | `nupp.serde.Error` | when the frame is malformed or of an unknown version | ### `encode` _function_ ```nupp function encode(binding: core.Binding, borrows value: T): string ``` Encodes a value as a frame. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `binding` | `core.Binding\` | the value's binding | | `borrows value` | `T` | the value | #### Returns | Type | Description | | --- | --- | | `string` | the frame | #### Raises | Type | Condition | | --- | --- | | `nupp.serde.Error` | when a value cannot be represented, at its path | ### `encodeDocument` _function_ ```nupp function encodeDocument(adapter: core.DocumentAdapter, borrows value: D): string ``` Encodes a document's contents as a frame, keeping every scalar's exact form. ```nupp local document = require("nupp.serde.document") local native = require("nupp.serde.native") local value = document.list({document.numberToken("1e400"), document.bytes("\0\1")}) local restored = native.decodeDocument(document.adapter(), native.encodeDocument(document.adapter(), value)) assert(restored:at(1):numberToken() == "1e400" and restored:at(2):bytes() == "\0\1") ``` #### Type parameters | Name | Description | | --- | --- | | `D` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `adapter` | `core.DocumentAdapter\` | the document adapter, such as `nupp.serde.document.adapter` | | `borrows value` | `D` | the document | #### Returns | Type | Description | | --- | --- | | `string` | the frame | ## Values ### `identity` _variable_ ```nupp const identity: table ``` Identifies this codec in a `nupp.serde.Context` it attaches.