Enrich CRUD API output with metadata

This patch changes output format of CRUD API from objects to rows
+ metadata.

Before:
```lua
crud.insert('customers', {
    id = 1, name = 'Name', age = 1,
})
---
- bucket_id: 1
  age: 1
  name: Name
  id: 1
...
```

After:
```lua
crud.insert('customers', {
    id = 1, name = 'Name', age = 1,
})
---
- - rows:
     - [1, 1, 1, 'Name']
    metadata:
     - name: id
       type: unsigned
     - name: bucket_id
       type: unsigned
     - name: age
       type: unsigned
     - name: name
       type: string

```

It's useful when user call crud functions via connectors and (s)he
doesn't really need to deserialize tuples to map.

Need for #6

Author: olegrok

CHANGELOG.md

@@ -18,6 +18,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
  * replace
  * upsert
 
+* Output format for CRUD operations changed to set of rows and metadata
+
 ### Changed
 
 * `checks` is disabled for internal functions by default

README.md

@@ -40,10 +40,14 @@ crud.insert('customers', {
     id = 1, name = 'Elizabeth', age = 23,
 })
 ---
-- bucket_id: 7614
-  age: 23
-  name: Elizabeth
-  id: 1
+---
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows:
+  - [1, 477, 'Elizabeth', 23]
 ...
 ```
 
@@ -67,10 +71,13 @@ Returns object, error.
 ```lua
 crud.get('customers', 1)
 ---
-- bucket_id: 7614
-  age: 23
-  name: Elizabeth
-  id: 1
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows:
+  - [1, 477, 'Elizabeth', 23]
 ...
 ```
 
@@ -95,10 +102,13 @@ Returns updated object, error.
 ```lua
 crud.update('customers', 1, {{'+', 'age', 1}})
 ---
-- bucket_id: 7614
-  age: 24
-  name: Elizabeth
-  id: 1
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows:
+  - [1, 477, 'Elizabeth', 24]
 ...
 ```
 
@@ -122,11 +132,13 @@ Returns deleted object, error.
 ```lua
 crud.delete('customers', 1)
 ---
-- bucket_id: 7614
-  age: 24
-  name: Elizabeth
-  id: 1
-...
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows:
+  - [1, 477, 'Elizabeth', 24]
 ```
 
 ### Replace
@@ -151,10 +163,13 @@ crud.replace('customers', {
     id = 1, name = 'Alice', age = 22,
 })
 ---
-- bucket_id: 7614
-  age: 22
-  name: Alice
-  id: 1
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows:
+  - [1, 477, 'Alice', 22]
 ...
 ```
 
@@ -177,9 +192,16 @@ Returns nil, error.
 **Example:**
 
 ```lua
-crud.upsert('customers', {id = 1, name = 'Alice', age = 22,}, {{'+', 'age', 1}})
+crud.upsert('customers',
+    {id = 1, name = 'Alice', age = 22,},
+    {{'+', 'age', 1}})
 ---
-- nil
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows: []
 ...
 ```
 
@@ -222,26 +244,18 @@ Each condition is a table `{operator, field-identifier, value}`:
 ```lua
 crud.select('customers', {{'<=', 'age', 35}})
 ---
-- - bucket_id: 10755
-    age: 35
-    name: Jack
-    id: 5
-  - bucket_id: 8011
-    age: 33
-    name: David
-    id: 3
-  - bucket_id: 16055
-    age: 25
-    name: William
-    id: 6
-  - bucket_id: 2998
-    age: 18
-    name: Elizabeth
-    id: 7
-  - bucket_id: 7614
-    age: 12
-    name: Elizabeth
-    id: 1
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows:
+  - [5, 1172, 'Jack', 35]
+  - [3, 2804, 'David', 33]
+  - [6, 1064, 'William', 25]
+  - [7, 693, 'Elizabeth', 18]
+  - [1, 477, 'Elizabeth', 12]
+...
 ```
 
 ### Pairs

crud.lua

@@ -11,6 +11,7 @@ local update = require('crud.update')
 local upsert = require('crud.upsert')
 local delete = require('crud.delete')
 local select = require('crud.select')
+local utils = require('crud.common.utils')
 
 local crud = {}
 
@@ -56,6 +57,10 @@ crud.select = select.call
 -- @function pairs
 crud.pairs = select.pairs
 
+-- @refer utils.unflatten_rows
+-- @function unflatten_rows
+crud.unflatten_rows = utils.unflatten_rows
+
 --- Initializes crud on node
 --
 -- Exports all functions that are used for calls

crud/common/utils.lua

@@ -157,4 +157,20 @@ function utils.convert_operations(user_operations, space_format)
     return converted_operations
 end
 
+function utils.unflatten_rows(rows, metadata)
+    if metadata == nil then
+        return nil, UnflattenError:new('Metadata is not provided')
+    end
+
+    local result = table.new(#rows, 0)
+    local err
+    for i, row in ipairs(rows) do
+        result[i], err = utils.unflatten(row, metadata)
+        if err ~= nil then
+            return nil, err
+        end
+    end
+    return result
+end
+
 return utils

crud/delete.lua

@@ -31,7 +31,7 @@ function delete.init()
     })
 end
 
---- Deletes tuple from the specifed space by key
+--- Deletes tuple from the specified space by key
 --
 -- @function call
 --
@@ -81,12 +81,10 @@ function delete.call(space_name, key, opts)
     end
 
     local tuple = results[replicaset.uuid]
-    local object, err = utils.unflatten(tuple, space:format())
-    if err ~= nil then
-        return nil, DeleteError:new("Received tuple that doesn't match space format: %s", err)
-    end
-
-    return object
+    return {
+        metadata = table.copy(space:format()),
+        rows = {tuple},
+    }
 end
 
 return delete

crud/get.lua

@@ -81,12 +81,10 @@ function get.call(space_name, key, opts)
     end
 
     local tuple = results[replicaset.uuid]
-    local object, err = utils.unflatten(tuple, space:format())
-    if err ~= nil then
-        return nil, GetError:new("Received tuple that doesn't match space format: %s", err)
-    end
-
-    return object
+    return {
+        metadata = table.copy(space:format()),
+        rows = {tuple},
+    }
 end
 
 return get

crud/insert.lua

@@ -63,7 +63,7 @@ function insert.call(space_name, obj, opts)
     end
     local space_format = space:format()
 
-    -- compute default buckect_id
+    -- compute default bucket_id
     local tuple, err = utils.flatten(obj, space_format)
     if err ~= nil then
         return nil, InsertError:new("Object is specified in bad format: %s", err)
@@ -92,12 +92,10 @@ function insert.call(space_name, obj, opts)
     end
 
     local tuple = results[replicaset.uuid]
-    local object, err = utils.unflatten(tuple, space_format)
-    if err ~= nil then
-        return nil, InsertError:new("Received tuple that doesn't match space format: %s", err)
-    end
-
-    return object
+    return {
+        metadata = table.copy(space_format),
+        rows = {tuple},
+    }
 end
 
 return insert

crud/replace.lua

@@ -89,12 +89,10 @@ function replace.call(space_name, obj, opts)
     end
 
     local tuple = results[replicaset.uuid]
-    local object, err = utils.unflatten(tuple, space_format)
-    if err ~= nil then
-        return nil, ReplaceError:new("Received tuple that doesn't match space format: %s", err)
-    end
-
-    return object
+    return {
+        metadata = table.copy(space_format),
+        rows = {tuple},
+    }
 end
 
 return replace

crud/select.lua

@@ -228,11 +228,16 @@ function select_module.pairs(space_name, user_conditions, opts)
             return nil
         end
 
-        local obj, err = iter:get()
+        local tuple, err = iter:get()
         if err ~= nil then
             error(string.format("Failed to get next object: %s", err))
         end
 
+        local obj, err = utils.unflatten(tuple, iter.space_format)
+        if err ~= nil then
+            error(string.format("Failed to unflatten next object: %s", err))
+        end
+
         return iter, obj
     end
 
@@ -260,7 +265,7 @@ function select_module.call(space_name, user_conditions, opts)
         return nil, err
     end
 
-    local objects = {}
+    local tuples = {}
 
     while iter:has_next() do
         local obj, err = iter:get()
@@ -272,10 +277,13 @@ function select_module.call(space_name, user_conditions, opts)
             break
         end
 
-        table.insert(objects, obj)
+        table.insert(tuples, obj)
     end
 
-    return objects
+    return {
+        metadata = table.copy(iter.space_format),
+        rows = tuples,
+    }
 end
 
 return select_module

crud/select/iterator.lua

@@ -191,12 +191,7 @@ function Iterator:get()
         end
     end
 
-    local object, err = utils.unflatten(tuple, self.space_format)
-    if err ~= nil then
-        return nil, GetTupleError:new("Received tuple that doesn't match space format: %s", err)
-    end
-
-    return object
+    return tuple
 end
 
 return Iterator