{"id":20056211,"url":"https://github.com/devgru/node-tarantool","last_synced_at":"2025-05-05T13:33:38.987Z","repository":{"id":66725644,"uuid":"9752594","full_name":"devgru/node-tarantool","owner":"devgru","description":"A node.js connector for Tarantool \u003c= 1.5","archived":false,"fork":false,"pushed_at":"2014-04-27T22:15:04.000Z","size":308,"stargazers_count":8,"open_issues_count":2,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-17T19:31:26.424Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devgru.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-29T16:30:10.000Z","updated_at":"2021-09-25T16:07:33.000Z","dependencies_parsed_at":"2023-02-20T10:15:16.732Z","dependency_job_id":null,"html_url":"https://github.com/devgru/node-tarantool","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devgru%2Fnode-tarantool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devgru%2Fnode-tarantool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devgru%2Fnode-tarantool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devgru%2Fnode-tarantool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devgru","download_url":"https://codeload.github.com/devgru/node-tarantool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252506682,"owners_count":21759098,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T12:52:30.413Z","updated_at":"2025-05-05T13:33:38.752Z","avatar_url":"https://github.com/devgru.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Connector - high-level [Tarantool](http://tarantool.org) driver\n\nConnector implements [Tarantool binary protocol](https://github.com/mailru/tarantool/blob/master/doc/box-protocol.txt) and exposes nice interface to access Tarantool.\n\nConnector uses [Transport](https://github.com/devgru/node-tarantool-transport) to compose and parse request and response headers.\n\n## NPM\n\n```shell\nnpm install tarantool\n```\n\n## Notes on Tarantool Connector\n\nConnector hides protocol-related stuff under the hood but there are things to know about before using it.\n\nTarantool database consists of Spaces (tables) and Tuples (rows). Spaces have no name, only numeric id.\n\nThis module provides three interfaces — Connection, Mapping and Space.\n\nConnection contains methods to send all kinds of requests, but arguments (and results) are binary Tuples — not usable.\n\nMapping knows how to convert Object to Tuple and vice versa (thanks to `spec`) and Space is a Mapping with specified space id.\n\nCall `ping` on Connector, `call` on Mapping and `insert`, `select`, `update`, `delete` on Space.\n\n## Object-to-Tuple binding specification — `spec`\n\nThere are three inner types in Tarantool storage: `int32`, `int64` and `buffer` (octet string). **All integers (options, flags, fields, space ids) are unsigned.**\n\nConnector can encode some pseudo-types:\n- `int32`: Unsigned 32-bit integer.\n- `int53`: Stored as internal `int64`. A native unsigned JS Number limited to 53 bit, stored natively without lost of significance.\n- `int64`: Accepts and returns `BigNum` objects from [`bignum`](https://github.com/justmoon/node-bignum).\n- `buffer`: Raw binary buffer.\n- `string`: Stored as `buffer` UTF-8 string.\n- `object`: Stored as `buffer` UTF-8 string with JSON content.\n\nIn order to use custom type, instead of providing it's name, pass object having `pack: (value) -\u003e buffer` and `unpack: (buffer) -\u003e value` methods as in example below.\n\nBuild `spec` object to map Object and Tuples to each other. Tarantool knows nothing about field names or types and Mapping maps them depending on `spec`.\n\nExample of valid `spec`:\n```coffee\nspec = id: 'int32', name: 'string', flags: 'object', smth_hard: {pack: ((value) -\u003e ...), unpack: ((buffer) -\u003e ...)}\n```\n\nWe specify three field-related things: order, name and type. `spec` tells Mapping which place should every field take and how to convert it.\n\n*Use any string containing '32' to specity int32 type, same for 53 and 64*\n\n## API\n\n### Connection\n\n`tc` stands for Tarantool Connection\n\n```coffee\n# create Connection using default Transport\n# default port is 33013\ntc = Tarantool.connect port, host, callback\n# OR create Connection using Transport, any object, with `request(type, body, callback)`\n# tc = new Tarantool transport\n\n# make use of connection\ntc.insert space, tuple, [flags,] callback\ntc.select space, tuples, [index, [offset, [limit,]]] callback\ntc.update space, tuple, [operations, [flags,]] callback\ntc.delete space, tuple, [flags,] callback\ntc.call proc, tuple, [flags,] callback\ntc.ping callback\n\n```\n\n- `space`, `flags`, `offset` and `limit` are Integers\n- `space` is Space number\n- `flags` is optional field, [possible values](https://github.com/mailru/tarantool/blob/master/doc/box-protocol.txt#L231) are stored in `Tarantool.flags` in camelCase, e.g. Tarantool.flags.returnTuple\n- `offset` and `limit` are optional, use them to specify ammount of returned with select\n- `tuples` is an Array of tuples\n- `tuple` is an Array of Fields, each Field is Buffer\n- `proc` is a String\n- `operations` is an Array of `operation`, they are constructed via Mapping or Space methods (see below)\n- `callback` is a Function that is called as `callback (returnCode, body)` where `body` is an Array of `tuples` or a Number or an error string if `returnCode` is non-zero.\n\n### Mapping\n\nUse Mapping to access several spaces with similar structure.\n\nMapping API:\n```coffee\n# creating mapping with specified spec\nmapping = tc.mapping spec\n\n# forgetting about tuples\nmapping.insert space, object, [flags,] callback\nmapping.select space, objects, [index, [offset, [limit,]]] callback\nmapping.update space, object, [operations, [flags,]] callback\nmapping.delete space, object, [flags,] callback\nmapping.call proc, object, [flags,] callback\n```\n\n`callback` will be called as `callback (returnCode, body)` where `body` is an Array of *Objects* or a Number or an error string if `returnCode` is non-zero.\n\n```coffee\n# creating operations list — see below\nmapping.assign argument\nmapping.add argument\nmapping.and argument\nmapping.xor argument\nmapping.or argument\nmapping.delete argument\nmapping.insertBefore argument\nmapping.splice spliceArgument\n```\n\n`spliceArgument` is a Hash (Object) with three keys: `string` (String), `offset` (Number) and `length` (Number).\n\n`argument` is a Hash (Object) with single key.\n\n\n### Space\n\nSpace incapsulates Mapping and space number to give you shortest API:\n\n```coffee\n# creating Space with spec\nspace = tc.space space, spec\n# OR with mapping\n# mapping = tc.mapping spec\n# space = tc.space space, mapping\n\nspace.insert object, [flags,] callback\nspace.select objects, [index, [offset, [limit,]]], callback\nspace.update object, [operations, [flags,]] callback\nspace.delete object, [flags,] callback\n\n# creating operations list\nspace.assign argument\nspace.add argument\nspace.and argument\nspace.xor argument\nspace.or argument\nspace.delete argument\nspace.insertBefore argument\nspace.splice spliceArgument\n```\n\n### Operations\n\nTarantool's update deals with \"operations\" — atomic field actions.\n\nHere's an example:\n\n```coffee\nspec = id: 'i32', name: 'string', winner: 'i32'\nuserSpace = tc.space 2, spec\noperations = [\n    userSpace.or winner: 1\n    userSpace.splice name: offset: 0, length: 0, string: '[Winner] '\n]\nuserSpace.update { id: userId }, operations, -\u003e\n    console.log 'winner now has [Winner] tag before his name'\n```\n\n## TODO\n- check if Buffer.concat is fast enough, if it is slow - replace with array of buffers, concat only before transport.request\n- check argument type in operations\n- catch socket errors and reconnect\n- write about Tarantool keys and multi-object select\n- write tests\n\n## Bugs and issues\nBug reports and pull requests are welcome.\n\n### LICENSE\nTarantool Connector for node.js is published under MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevgru%2Fnode-tarantool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevgru%2Fnode-tarantool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevgru%2Fnode-tarantool/lists"}