qb1-type-base

Definitions for the fundamental types that underpin qb1 serialization.

Note that this is the raw base module and includes no parsing or normalization of names.
Use qb1-obj2type for easier conversion to and from simple objects.

Overview

qb1-type-base defines the types which support reading and writing structured information. These types include JSON types plus refined types strongly related to the JSON types:

qb1 and JSON        qb1 only

object
array

number              decimal
                    integer
                    uinteger    (unsigned integer)
                    float
                    rational
                    byte

string              blob

boolean     

null
true
false

'qb1 only' types are compatible with and auto-conversion to and from number and string to allow seamless compatibility with JSON.

Representing Types as Simple Strings

fullname              name            tinyname    description 
                      
number                num             n           a JSON number (plus float or rational, if desired)
string                str             s           a string of characters
[number]              [num]           [n]         an array of numbers (integer, decimal, float...)
{string:number}       {str:num}       {s:n}       an object with number values
[string|number|null]  [str|num|nul}   [s|n|N]     an array containing strings or numbers or null

Types as JSON

Like string format, but in JSON:

fullname              name            tinyname    description 
                      
"number"              "num"           "n"         a JSON number (or base 2 float or rational)
"string"              "str"           "s"         a string of characters
["number"]            ["num"]         ["n"]       an array of numbers (integer, decimal, float...)
{"string":"number"}   {"str":"num"}   {"s":"n"}   an object with number values

You can use short, long and mini forms interchangeably with qb1.

Basic Types

This brief overview of qb1 types is covered in more detail in the qb1-typex project. While perusing the types, keep in mind that none of these types have upper limits. number, string, integer, etc have no bounds. See the Constraints section for options on constraining values to desired size limits.

JSON Tokens

null                    same token as in JSON, usable anywhere a value can be used

JSON Types

number                  signed or unsigned integer or decimal value
string                  string of characters encoded as UTF-8
object                  a dictionary or map with string keys and any values
array                   ordered list of any values

JSON Number Sub-Types

These numeric are all represented directly in JSON. Note that while decimal is the JSON format used for floating point numbers, it may not be an ideal fit for serialization from systems that use base 2 floating point or rational numbers, which are supported options in qb1.

decimal                 base 10 floating point number
integer                 signed integer
unteger                 unsigned integer

Other Numeric Types (representable as JSON object or string)

float                   base 2 floating point number
rational                a rational number expressed as a fraction p/q

Binary Types (representable in JSON as integers or arrays of integer - as well as object with compact string encodings)

blob                    array of bytes
byte                    eight bit unsigned integer (values 0..255)

Boolean (representable as both true/false or byte or integer 1/0)

boolean                 can be true or false

Special Types

type                    type is a type definition
any or *                is a wild-card representing any valid type within a chosen type-set

Full, Short, Mini, and Numeric Representations

Every token and type has three string identities - full name (called 'name'), short (3-letter called 'nam', and single character or 'char'. Single character identities are common ascii (in range 0..127) and so are also a small integer representation of type.

Short names and characters are easy to remember because 'nam' is almost always the first three letters of name and char is almost always the first letter of name. Tokens (single value types) are capitalized while other types, with the exception of blob, are lower case.

name        nam     char    ascii

null        nul     N       
number      num     n
string      str     s
object      obj     o
array       arr     a
decimal     dec     d
integer     int     i
untiger     unt     u 
rational    rat     r
boolean     boo     b 
type        typ     t
float       flt     f               // exception to name convention
any         any     *               // exception to char convention
blob        blb     X               // exception to char convention               
byte        byt     x               // exception to char convention

Compound Types

type-def does not handle compound types but qb1 does. See qb1-typex-set or qb1-typex for more information on compound types like [str|int|boo] (array of string-or-integer-or-boolean))

Number Size Constraints (bits)

qb1 has integrated support for the popular bit size constraints across all numeric types.

name                            description
                                
integer8                        8 bit signed integer                                    
int8                            8 bit signed integer
i8                              8 bit signed integer
unt8                            8 bit unsigned integer (same as 'byt')
flt32                           32 bit float
f32                             32 bit float (short-code)
dec64                           64 bit decimal
d64                             64 bit decimal (short-code)
rational64                      64 bit rational
...

The pre-defined number sizes are limited to the common sizes 8, 16, 32, 64, or 128 for integer and uinteger and 32, 64, or 128 for float, decimal or rational.

More examples are given in the full list of size-constrained numbers below.

(why use bit size for number instead of bytes like we do for string/blob? Tradition. Using 'int8' for a 64 bit integer would be terribly misleading to most programmers)

String and Blob Size Constraints (bytes)

qb1 has integrated suppport for byte size constraints for string and blob types

string           str              s            string with limit of n characters
blob             blb              X            array of n bytes

For example

str32  -    a string of 32 bytes or less
blb512 -    a blob of 512 bytes or less

Note that we very intentionally chose byte constraints, not character constraints for both strings and blobs because character limits are a business concern while byte limits are a storage and serialization concern, which is qb1's focus. With qb1, concrete physical limits take precedence.

Compound Types, Binary Interoperability and More...

Coming soon...

Design Notes

Static

All base types are implemented to be used, as if they were immutable. Though properties are not actually immutable, the base type API guides users to create types with all properties up front.

Custom Properties (type.cust)

Types support a custom object property called 'cust' where clients can store information within a type graph. This information will be included in the type toString() as well as in to_obj() calls by default under the cust property. By default this property is defined as an any-type '*' and properties set on it will be serialized via type.toString() and type.obj(). The properties serialized can be controlled by setting cust.$type to a more specific definition, for example:

var obj2type = require('qb1-obj2type')

var cust_type = obj2type({ file: 'str', count: 'int' } })
mytype.cust = {
    $type: cust_type,
    file: 'cache.json', 
    count: 0
}

The custom type defined this way is implemented as an extension of the base 'type', so in serialization instead of

{ $type: 'type', $value: ... }, 

we will would see the extension:

{ $type: { $base: 'type', cust: { file: 'str', count: 'int' } }, $value: ... }

For example:

{
    // instead of $type: 'type', we get:
    $type: [ { $base: 'type', cust: { file: 'str', count: 'int' } } ],
    $value: [
        {
            '*': {
                name: 's',
                description: { base: 's', $cust: { file: 'cache.json', count: 2522 } },
                maintainers: [],
                keywords: ['s'],
                license: { $mul: [ 's', { type: 's', url: 's', description: 's', copyright: 's' }, [{type: 's', url:'s'}] ] },
                readmeFilename: 's',
                time: { $mul: ['s', {modified: 's'}] },
                versions: { '*': 's' },
                homepage: 's',
                bugs: { url: 's', email: 's' },
                repository: { $mul: [
                    { type: 's', url: 's', path: 's', web: 's', private: 'b', git: 's', scripts: {}, dist: 's', github: 's' },
                    [{ type: 's', url: 's', path: 's', web: 's', private: 'b', git: 's', scripts: {}, dist: 's', github: 's' }]
                ] },
                users: {
                    '*': 'b',
                },
                contributors: { $mul: [{ name: 's', email: 's', url: 's' }, [{ name: 's', email: 's', url: 's' }], 's' ] },
                author: { name: 's', email: 's', url: 's' },
                'dist-tags': { '*': 's' },                
                $cust: { file: 'cache.json', count: 'int' }, 
            },
            $cust: { file: 'cache.json', count: 32633 }
        }
    ]
}

You can use the addenda ($add) property to give equivalent information, but leave the basic type-graph cleaner and easier to read:

{
    $typ: [ { $base: type, cust: { file: str, count: int } } ],
    $val: [
        {
            '*': {
                name: 's',
                description: 's',
                maintainers: [],
                keywords: ['s'],
                license: { $mul: [ 's', { type: 's', url: 's', description: 's', copyright: 's' }, [{type: 's', url:'s'}] ] },
                readmeFilename: 's',
                time: { $mul: ['s', {modified: 's'}] },
                versions: { '*': 's' },
                homepage: 's',
                bugs: { url: 's', email: 's' },
                repository: { $mul: [
                    { type: 's', url: 's', path: 's', web: 's', private: 'b', git: 's', scripts: {}, dist: 's', github: 's' },
                    [{ type: 's', url: 's', path: 's', web: 's', private: 'b', git: 's', scripts: {}, dist: 's', github: 's' }]
                ] },
                users: {
                    '*': 'b',
                },
                contributors: { $mul: [{ name: 's', email: 's', url: 's' }, [{ name: 's', email: 's', url: 's' }], 's' ] },
                author: { name: 's', email: 's', url: 's' },
                'dist-tags': { '*': 's' },                
            }
        }
    ],
    // separate the custom properties into addenda using the serialization option { addenda: [ '0/cust' ] }  
    $add: {
        'cust': {
            '.':              { file: 'cache.json', count: 32633 },
            '*':              { file: 'cache.json', count: 82552 }, 
            '*/description':  { file: 'cache.json', count: 2522 }
        }
    }
}