Types and units#

The document operations use typed values, and the database operations add time values. The tables use the type names of your selected language. Use it to find the unit, range, default, and absent value of a field.

Text uses UTF-8. This includes string values, object keys, and JSON, DUST, and EDN input and output. The document builders reject invalid UTF-8 strings and keys. TRON is binary, but its strings and keys also use UTF-8. Byte lengths count encoded bytes, rather than characters.

This matches JSON's UTF-8 requirement for interchange (RFC 8259, section 8.1).

Evaluation and database read results recursively omit object fields containing empty objects or arrays. This includes objects emptied by nested omissions. Null, empty strings, false, zero and array positions stay intact. Input documents and expanded programs preserve their contents.

• Time and units defines the tick, its range and resolution, and the host conversion.
• Value types defines documents, formats, node IDs, transactions, entities, instants, durations, numbers, and bytes.
• Other kinds defines the remaining parameter and result kinds, such as text and counts.

Time and units#

The ABI uses one time unit: the 100 ns tick, stored as an i64 count.

• A duration is a signed tick count.
• An instant is the tick count since the Unix epoch, 1970-01-01T00:00:00Z. It is in UTC, with no leap seconds and no time zone.
• DUST durations and UTC values use the same unit, so database data and API parameters need no unit conversion.

Range#

An i64 tick count holds approximately 29,227 years on each side of the Unix epoch:

This covers all written history, including cuneiform from approximately 3400 BCE.

Resolution#

One tick is 100 ns, or 0.0000001 s.

Thread wake-up jitter on common platforms is microseconds, so a smaller unit gives no useful precision. Windows also counts time in 100 ns units.

Order and time zones#

• Integer ticks have no floating-point rounding. ABI numbers are i64 or f64 only.
• An instant in UTC ticks has no time zone or daylight-saving state. Each instant has one meaning, and integer comparison gives the time order.
• The host applies time zones for presentation.
• Each binding uses the duration and instant types of its language and converts at the call boundary.

Rust conversion#

Rust uses std::time::Duration and std::time::SystemTime.

• Duration has no sign. A negative tick count converts to zero, or to None when a negative value has a meaning: a negative lock_timeout waits without limit.
• Conversion to ticks truncates sub-tick nanoseconds toward zero.
• A Duration beyond the i64 tick range saturates.
• A SystemTime is UNIX_EPOCH plus or minus the tick count. An instant outside the host range causes invalid_argument with code time_out_of_range.
• None shows an absent instant.

Value types#

Each value type has one meaning in every language. Types below use the selected language's spelling.

document#

An owned native document preserves ordered members and duplicate keys.

format#

The format selects a text codec or binary TRON.

node_id#

A node ID selects a node within its owning document.

transaction#

A transaction selects a committed database snapshot.

entity#

An entity identifies an object in a database.

instant#

An instant counts 100 ns ticks since the Unix epoch. An instant outside the host range reports time_out_of_range.

duration#

A duration counts 100 ns ticks. Conversions beyond a host duration range saturate.

number#

A number is a signed integer or finite floating-point value.

bytes#

Bytes contain a borrowed byte sequence with an explicit length.

Other kinds#

These kinds have no value type of their own. The signature of each operation gives the exact type. Parameter tables link handle and record kinds to the operation or record that defines them.

Binding mechanics#

Bindings may include these arguments in addition to native operation arguments:

Optional wrappers such as pointers, Option and Maybe keep the wrapped type's contract.

Record examples#

The generator captured each result from the native library.

Activate the license from a token file#

let token = std::fs::read_to_string("license.token")?;
stardust::activate(token.trim())?;
let result = stardust::license()?;

{:value {:active              true
         :failure             "none"
         :support_end         72580320000000000
         :expires             nil
         :build               nil
         :refused_support_end nil
         :subject             "test"
         :license_id          "test"
         :name                ""
         :license             ""
         :tier                ""}}

Add a typed integer node#

let input = stardust::NodeInput { kind: Kind::NUMBER, number: Number::I64(41), ..Default::default() };
let mut builder = stardust::builder()?;
builder.add(input)?;
let result = input;

{:value {:parent  nil
         :kind    "number"
         :boolean false
         :number  41
         :key     ""
         :text    ""}}

database/merge_patch#

seed_text holds this document:

{:#_ada {:name "Ada"
         :role "engineer"
         :age  36}
 :#_bob {:name   "Bob"
         :role   "engineer"
         :age    41
         :mentor {:#link "#_ada"}}
 :#_cy  {:name "Cy"
         :role "designer"
         :age  29}
 :#_tx  {:author "smoke"
         :reason "seed"}}

let patch = stardust::parse(seed_text, Format::EDN)?;
let result = db.merge_patch(&patch, None)?;

{:value {:status       "committed"
         :transaction  4
         :facts        12
         :committed_at 17923367685039269
         :ids          {:#_ada 1
                        :#_bob 2
                        :#_cy  3}}}

database/mutation#

birthday_text holds this document:

{:query {:find  [?e]
         :where [[?e "name" "Ada"]]}
 :patch {:?e {:age 37}}}

let source = stardust::parse(birthday_text, Format::EDN)?;
let mutation = db.mutation(&source)?;
let result = mutation.run(None, &RunOptions::default(), None)?;

{:value {:status       "committed"
         :transaction  5
         :facts        1
         :committed_at 17923367687196265
         :ids          {}}}

database/patch_definition#

definition_text holds this document:

{:parameters {:?role "engineer"}
 :find       [?name]
 :where      [
   [?e "role" ?role]
   [?e "name" ?name]]
 :orderBy    [?name]}

let definition = stardust::parse(definition_text, Format::EDN)?;
let result = db.patch_definition("queries", "people/by_role", &definition)?;

{:value {:status       "committed"
         :transaction  3
         :facts        0
         :committed_at 17923367687832135
         :ids          {}}}

document/read#

input_text holds this document:

{:x 41}

let input = stardust::parse(input_text, Format::EDN)?;
let result = input.read(input.root()?)?;

{:value {:kind         "object"
         :boolean      false
         :parent       nil
         :position     0
         :first_child  1
         :next_sibling nil
         :key          ""
         :text         ""}}

document/read_many#

input_text holds this document:

{:x 41}

let input = stardust::parse(input_text, Format::EDN)?;
let views = input.read_many(input.root()?, 1)?;
let result = views.into_iter().next().ok_or("missing node view")?;

{:value {:kind         "object"
         :boolean      false
         :parent       nil
         :position     0
         :first_child  1
         :next_sibling nil
         :key          ""
         :text         ""}}

Read the process license#

let result = stardust::license()?;

{:value {:active              true
         :failure             "none"
         :support_end         72580320000000000
         :expires             nil
         :build               nil
         :refused_support_end nil
         :subject             "test"
         :license_id          "test"
         :name                ""
         :license             ""
         :tier                ""}}

mutation/close#

birthday_text holds this document:

{:query {:find  [?e]
         :where [[?e "name" "Ada"]]}
 :patch {:?e {:age 37}}}

let source = stardust::parse(birthday_text, Format::EDN)?;
let mutation = db.mutation(&source)?;
let result = mutation.run(None, &RunOptions::default(), None)?;
mutation.close();

{:value {:status       "committed"
         :transaction  5
         :facts        1
         :committed_at 17923367690415775
         :ids          {}}}

mutation/run#

birthday_text holds this document:

{:query {:find  [?e]
         :where [[?e "name" "Ada"]]}
 :patch {:?e {:age 37}}}

let source = stardust::parse(birthday_text, Format::EDN)?;
let mutation = db.mutation(&source)?;
let result = mutation.run(None, &RunOptions::default(), None)?;

{:value {:status       "committed"
         :transaction  5
         :facts        1
         :committed_at 17923367691241152
         :ids          {}}}

Open with explicit native options#

let options = stardust::Options { page_size: 0, ..Default::default() };
let _database = stardust::open(database_path, &options)?;
let result = options;

{:value {:create              true
         :clear               false
         :pin_memory          false
         :page_size           0
         :lock_timeout        0
         :initial_map_bytes   0
         :commit_batch        0
         :plugins             nil
         :memory_budget_bytes 0}}

Wait for the database lock without a limit#

let options = stardust::Options { page_size: 0, lock_timeout: None, ..Default::default() };
let _database = stardust::open(database_path, &options)?;
let result = options;

{:value {:create              true
         :clear               false
         :pin_memory          false
         :page_size           0
         :lock_timeout        nil
         :initial_map_bytes   0
         :commit_batch        0
         :plugins             nil
         :memory_budget_bytes 0}}

Capture the host duration boundary#

query_text holds this document:

{:find    [?name]
 :where   [[?e "name" ?name]]
 :orderBy [?name]}

boundary_text holds this document:

9223372036854775807

let definition = stardust::parse(query_text, Format::EDN)?;
let query = db.query(&definition)?;
let boundary = stardust::parse(boundary_text, Format::EDN)?;
let seconds = boundary.i64(boundary.root()?)? as u64;
let options = RunOptions { page_size: 2, max_cost: std::time::Duration::from_secs(seconds), ..Default::default() };
let _rows = query.run(None, &options, None)?;
let result = options;

{:value {:page_size 2
         :max_cost  9223372036854775807
         :as_of     0}}

Truncate a positive sub-tick duration#

query_text holds this document:

{:find    [?name]
 :where   [[?e "name" ?name]]
 :orderBy [?name]}

boundary_text holds this document:

99

let definition = stardust::parse(query_text, Format::EDN)?;
let query = db.query(&definition)?;
let boundary = stardust::parse(boundary_text, Format::EDN)?;
let nanos = boundary.i64(boundary.root()?)? as u64;
let options = RunOptions { page_size: 2, max_cost: std::time::Duration::from_nanos(nanos), ..Default::default() };
let _rows = query.run(None, &options, None)?;
let result = options;

{:value {:page_size 2
         :max_cost  0
         :as_of     0}}

Run with typed query options#

query_text holds this document:

{:find    [?name]
 :where   [[?e "name" ?name]]
 :orderBy [?name]}

let definition = stardust::parse(query_text, Format::EDN)?;
let query = db.query(&definition)?;
let options = RunOptions { page_size: 2, max_cost: std::time::Duration::from_secs(1), ..Default::default() };
let _rows = query.run(None, &options, None)?;
let result = options;

{:value {:page_size 2
         :max_cost  10000000
         :as_of     0}}

Read the complete initial subscription event#

query_text holds this document:

{:find    [?name]
 :where   [[?e "name" ?name]]
 :orderBy [?name]}

let definition = stardust::parse(query_text, Format::EDN)?;
let query = db.query(&definition)?;
let mut subscription = query.subscribe(None, &RunOptions::default())?;
let event = subscription.next().await?.ok_or("no initial event")?;
let result = event;

{:value {:sequence    1
         :superseded  0
         :transaction 4
         :result      [{:name "Ada"} {:name "Bob"} {:name "Cy"}]}}