src/README.md

   1 # ucode library for creating and using read-only hashtable files
   2
   3 This allows fast lookup on files with lots of entries. Read-only hash table
   4 files support json compatible data with objects that can selectively be turned
   5 into hash tables for fast lookup.
   6 These files can be loaded via mmap, to make it easy to share them across
   7 processes and not have to keep contents in RAM at all times.
   8 Any values inside the file are de-duplicated at creation time and referenced
   9 via offsets.
  10
  11 ## Create hashtable files
  12
  13 ```javascript
  14 let obj = {
  15         // example data
  16         hashtbl1: {
  17                 "foo": "bar",
  18                 //...
  19         },
  20         hashtbl2: {
  21                 "foo": "bar1",
  22                 //...
  23         }
  24 };
  25
  26 let uht = require("uht");
  27 uht.mark_hashtable(obj.hashtbl1);
  28 uht.mark_hashtable(obj.hashtbl2);
  29 uht.save("filename.bin", obj);
  30 ```
  31
  32 ## Use hashtable files
  33
  34 ```javascript
  35 // Load File
  36 let uht = require("uht");
  37 let file = uht.open("filename.bin");
  38
  39 // get outer object (not marked as hashtable)
  40 let data = file.get();
  41
  42 // look up value from inner object
  43 let val = file.get(data.hashtbl1, "foo");
  44 warn(`value: ${val}\n`); // returns "value: bar"
  45 ```
  46
  47
  48 ## API:
  49
  50 ### `uht.save(filename, value)`
  51
  52 Saves a ucode value as a uht file. Supports any json compatible datatype
  53 (though most frequently used with an object).
  54 By default, no hashtables are embedded. Any object intended to be used as
  55 hashtable for faster lookup needs to be marked with `uht.mark_hashtable(obj)`
  56 Arbitrary nesting is supported.
  57
  58 ### `uht.mark_hashtable(obj)`
  59
  60 Mark an object for hashtable. This adds a key as marker, by default `"##hash": true`.
  61
  62 ### `uht.set_hashtable_key(key)`
  63
  64 Set the marker key used to mark objects as hashtables. Must be used before
  65 writing or dumping hashtables.
  66
  67 ### `ht = uht.open(filename)`
  68
  69 Open a uht binary file and return a resource.
  70 Returns null on failure.
  71
  72 ### `ht.get(val, key, dump)`
  73
  74 When used without arguments, it returns the outermost value of the uht file
  75 (typically an object). If dump is true, embedded hashtables are returned
  76 as ucode objects. This is useful for dumping or rewriting into a new file after
  77 modifications.
  78 val can be used to reference embedded hashtables (obtained by previous `get()`
  79 calls with `dump=false`).
  80 If `key` is given, it performs a hashtable lookup and returns the result.
  81 `val` may only be `null`, if the outer object is itself a hash table.