{"_id":"@charlieduong94/gremlin","_rev":"4-7dea67d56657141afca6f41f537838dd","name":"@charlieduong94/gremlin","time":{"modified":"2022-04-04T22:32:24.123Z","created":"2018-01-31T17:13:10.050Z","2.6.1":"2018-01-31T17:13:10.050Z","2.7.0":"2018-02-01T21:00:10.954Z"},"maintainers":[{"email":"charlieduong94@gmail.com","name":"charlieduong94"}],"dist-tags":{"latest":"2.7.0"},"versions":{"2.7.0":{"name":"@charlieduong94/gremlin","version":"2.7.0","description":"JavaScript client for TinkerPop3 Gremlin Server","main":"lib/index.js","scripts":{"prebuild":"rimraf ./lib","build":"babel ./src -d lib --ignore '**/*.test.js'","build:umd":"NODE_ENV=production webpack src/index.js umd/gremlin.js","build:min":"NODE_ENV=production webpack -p src/index.js umd/gremlin.min.js","build:watch":"npm run build -- --watch","coverage":"babel-node ./node_modules/istanbul/lib/cli.js cover _mocha","coverage:travis":"babel-node ./node_modules/istanbul/lib/cli.js cover _mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage","examples:browser":"babel-node examples/server","examples:node":"babel-node examples/node-example","gremlin-server":"GREMLIN_SERVER_VERSION=3.2.4 docker-compose up -d","precommit":"lint-staged","prettify":"prettier --single-quote --trailing-comma all --write \"src/**/*.js\"","test":"NODE_TLS_REJECT_UNAUTHORIZED=0 mocha $(find src -path '*test.js') --compilers js:babel-register --recursive --reporter spec","test:watch":"npm run test -- --watch"},"lint-staged":{"gitDir":"../","*.js":["npm run prettify","git add"]},"repository":{"type":"git","url":"git+https://github.com/jbmusso/gremlin-javascript.git"},"keywords":["tinkerpop","gremlin","graphdb","graph","database"],"author":{"name":"Jean-Baptiste Musso","email":"jbmusso+github@gmail.com"},"license":"MIT","bugs":{"url":"https://github.com/jbmusso/gremlin-javascript/issues"},"homepage":"https://github.com/jbmusso/gremlin-javascript","dependencies":{"gremlin-template-string":"^2.0.0","highland":"^2.5.1","lodash":"^3.10.1","node-uuid":"^1.4.3","readable-stream":"^2.0.2","ws":"^2.3.1","zer":"^0.1.0"},"devDependencies":{"babel-cli":"^6.4.5","babel-core":"^6.4.0","babel-loader":"^6.2.1","babel-plugin-transform-async-to-module-method":"^6.5.2","babel-plugin-transform-object-rest-spread":"^6.23.0","babel-plugin-transform-runtime":"^6.5.2","babel-preset-env":"^1.4.0","babel-register":"^6.3.13","babelify":"^5.0.4","bluebird":"^3.3.3","browserify":"^9.0.3","chai":"^2.1.1","finalhandler":"^0.1.0","husky":"^0.13.4","istanbul":"^0.4.2","istanbul-coveralls":"^1.0.3","lint-staged":"^3.6.0","mocha":"^1.21.4","mocha-lcov-reporter":"^1.2.0","prettier":"^1.4.2","rimraf":"^2.6.1","serve-static":"^1.5.3","webpack":"^1.12.11"},"_id":"@charlieduong94/gremlin@2.7.0","_npmVersion":"5.5.1","_nodeVersion":"8.9.1","_npmUser":{"name":"charlieduong94","email":"charlieduong94@gmail.com"},"dist":{"integrity":"sha512-suQ8f0LPYz5SP6Cx+KbHIgG54i1kdO/r3fkV3gbfpGGt7c8Xcf1YmSL69IVHfCUI8aWA5dPIH5J/veDYAIXRwA==","shasum":"cfd479e46be8c24b81f22ec80d949c5eb7545dde","tarball":"https://registry.npmjs.org/@charlieduong94/gremlin/-/gremlin-2.7.0.tgz","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCOGtgySPOeIJGEWlOIQH0NgOQw4bL3O12JEZ92Qh2sKwIhALX1Nvzsn2fpf21BGqKwGBtUjO6qZqn9Z7EoDRSwlO/f"}]},"maintainers":[{"email":"charlieduong94@gmail.com","name":"charlieduong94"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/gremlin-2.7.0.tgz_1517518809382_0.17285949434153736"}}},"readme":"[![Build Status](https://travis-ci.org/jbmusso/gremlin-javascript.svg?branch=master)](https://travis-ci.org/jbmusso/gremlin-javascript) [![Coverage Status](https://coveralls.io/repos/github/jbmusso/gremlin-javascript/badge.svg?branch=master)](https://coveralls.io/github/jbmusso/gremlin-javascript?branch=master) [![npm](https://img.shields.io/npm/dt/gremlin.svg)](https://www.npmjs.com/package/gremlin)\n\ngremlin-javascript\n==================\n\nA WebSocket JavaScript client for TinkerPop3 Gremlin Server. Works in Node.js and modern browsers.\n\n## Installation\n\n```\nnpm install gremlin --save\n```\n\n## Quick start\n\n```javascript\nimport { createClient } from 'gremlin';\n\nconst client = createClient();\n\nclient.execute('g.V().has(\"name\", name)', { name: 'Alice' }, (err, results) => {\n  if (err) {\n    return console.error(err)\n  }\n\n  console.log(results);\n});\n```\n\n### Using ES2015/2016\n\n```javascript\nimport { createClient, makeTemplateTag } from 'gremlin';\n\nconst client = createClient();\nconst gremlin = makeTemplateTag(client);\n\nconst fetchByName = async (name) => {\n  const users = await gremlin`g.V().has('name', ${name})`;\n  console.log(users);\n}\n\nfetchByName('Alice');\n```\n\n### Experimental: JavaScript Gremlin language variant\n\nThis library has partial support for [Gremlin-JavaScript language variant](http://tinkerpop.apache.org/docs/3.2.4/reference/#_on_gremlin_language_variants). It currently sends Groovy strings (rather than bytecode) and automatically escapes primitives. However, it does not support sending anonymous functions. Under the hood, it serializes `Traversal` to Groovy using an early version of [zer](https://github.com/jbmusso/zer).\n\nThe following works with a recent version of Node.js (tested with v7.6.0):\n```javascript\nimport { createClient, statics } from 'gremlin';\n\nconst client = createClient();\nconst g = client.traversalSource();\nconst { both } = statics;\n\n// And then, within any async function:\n\nconst results = await g.V().repeat(both('created')).times(2).toPromise();\n// results.length === 16;\n```\n\n## Usage\n\n### Creating a new client\n\n```javascript\n// Assuming Node.js or Browser environment with browserify:\nimport Gremlin from 'gremlin';\n\n// Will open a WebSocket to ws://localhost:8182 by default\nconst client = Gremlin.createClient();\n```\nThis is a shorthand for:\n```javascript\nconst client = Gremlin.createClient(8182, 'localhost');\n```\n\nIf you want to use Gremlin Server sessions, you can set the `session` argument as true in the `options` object:\n```javascript\nconst client = Gremlin.createClient(8182, 'localhost', { session: true });\n```\n\nThe `options` object currently allows you to set the following options:\n* `session`: whether to use sessions or not (default: `false`)\n* `language`: the script engine to use on the server, see your gremlin-server.yaml file (default: `\"gremlin-groovy\"`)\n* `op` (advanced usage): The name of the \"operation\" to execute based on the available OpProcessor (default: `\"eval\"`)\n* `processor` (advanced usage): The name of the OpProcessor to utilize (default: `\"\"`)\n* `accept` (advanced usage): mime type of returned responses, depending on the serializer (default: `\"application/json\"`)\n* `path`: a custom URL connection path if connecting to a Gremlin server behind a WebSocket proxy\n* `ssl`: whether to use secure WebSockets or not (default: `false`)\n$ `rejectUnauthorized`: when using ssl, whether to reject self-signed certificates or not (default: `true`). Useful in development mode when using gremlin-server self signed certificates. Do NOT use self-signed certificates with this option in production.\n* `user` : username to use for SASL authentication\n* `password` : password to use for SASL authentication\n\n## Using SASL Authentication\n\nIf you want to use [SASL Authentication] (http://tinkerpop.apache.org/docs/3.2.5/dev/provider/#_authentication) with your gremlin server:\n\n```javascript\nimport { createClient } from 'gremlin';\n\nconst client = Gremlin.createClient(8182, 'localhost', { ssl:true, user:'user', password:'password' });\n\nclient.execute('g.V()', { }, (err, results) => {\n  if (err) {\n    return console.error(err)\n  }\n\n  console.log(results);\n});\n```\n\n### Executing Gremlin queries\n\nThe client currently supports three modes:\n* callback mode (with internal buffer)\n* promise mode\n* streaming moderesults\n* streaming protocol messages (low level API, for advanced usages)\n\n#### Callback mode: client.execute(script, bindings, message, callback)\n\nWill execute the provided callback when all results are actually returned from the server.\n\n```javascript\nclient.execute('g.V()', (err, results) => {\n  if (!err) {\n    console.log(results) // notice how results is *always* an array\n  }\n});\n```\n\nThe client will internally concatenate all partial results returned over different messages (depending on the total number of results and the value of `resultIterationBatchSize` set in your .yaml file).\n\nWhen the client receives the final `statusCode: 299` message, the callback will be executed.\n\n#### Promise/template mode: Gremlin.makeTemplateTag(client);\n\nThe EcmaScript2015 specification added support for Promise and tagged template literals to JavaScript. Gremlin client leverages these features and offers an alternative way to execute Gremlin queries.\n\n`makeTemplateTag(client)` will return a template function, or 'tag', bound to a given Gremlin client instance. Calling that template will return a `Promise` of execution of the given script using the registered client, while simultaneously escaping all parameters for performance and security concerns.\n\n```javascript\nimport { createClient, makeTemplateTag } from 'gremlin';\n\nconst client = createClient();\nconst gremlin = makeTemplateTag(client);\n\ngremlin`g.V().has('name', ${name})` // template tag that returns a Promise\n  .then((vertices) => {\n    console.log(vertices)\n  })\n  .catch((err) => {\n    // Something went wrong\n  })\n```\n\nFor easier debugging, you can also preview the raw query sent to Gremlin server:\n```javascript\nconst name = 'Bob';\nconst { query } = gremlin`g.V().has('name', ${name})`;\nconsole.log(query);\n// output:\n//   { gremlin: 'g.V().has(\\'name\\', p1)', bindings: { p1: 'Bob' } }\n```\n\nBecause the `gremlin` template literal returns a `Promise`, it can be used in conjunction with the async function proposal from ES2016 to execute Gremlin queries with a shortened syntax:\n\n```javascript\nconst fetchByName = async (name) => {\n  const users = await gremlin`g.V().has('name', ${name})`;\n  console.log(users);\n}\n\nfetchByName('Alice');\n```\n\n#### Stream mode\n\n##### client.stream(script, bindings, message)\n\nReturn a Node.js ReadableStream set in Object mode. The stream emits a distinct `data` event per query result returned by Gremlin Server.\n\nInternally, a 1-level flatten is performed on all raw protocol messages returned. If you do not wish this behavior and prefer handling raw protocol messages with batched results, prefer using `client.messageStream()`.\n\nThe order in which results are returned is guaranteed, allowing you to effectively use `order` steps and the like in your Gremlin traversal.\n\nThe stream emits an `end` event when the client receives the last `statusCode: 299` message returned by Gremlin Server.\n\n```javascript\nconst query = client.stream('g.V()');\n\n// If playing with classic TinkerPop graph, will emit 6 data events\nquery.on('data', (result) => {\n  // Handle first vertex\n  console.log(result);\n});\n\nquery.on('end', () => {\n  console.log('All results fetched');\n});\n```\n\nThis allows you to effectively `.pipe()` the stream to any other Node.js WritableStream/TransformStream.\n\n##### client.messageStream(script, bindings, message)\n\nA lower level method that returns a `ReadableStream` which emits the raw protocol messages returned by Gremlin Server as distinct `data` events.\n\nIf you wish a higher-level stream of `results` rather than protocol messages, please use `client.stream()`.\n\nAlthough a public method, this is recommended for advanced usages only.\n\n```javascript\nconst client = Gremlin.createClient();\n\nconst stream = client.messageStream('g.V()');\n\n// Will emit 3 events with a resultIterationBatchSize set to 2 and classic graph defined in gremlin-server.yaml\nstream.on('data', (message) => {\n  console.log(message.result); // Array of 2 vertices\n});\n```\n\n### Adding bound parameters to your scripts\n\nFor better performance and security concerns (script injection), you must send bound parameters (`bindings`) with your scripts.\n\n`client.execute()`, `client.stream()` and `client.messageStream()` share the same function signature: `(script, bindings, querySettings)`.\n\nNotes/Gotchas:\n- Any bindings set to `undefined` will be automatically escaped with `null` values (first-level only) in order to generate a valid JSON string sent to Gremlin Server.\n- You cannot use bindings whose names collide with Gremlin reserved keywords (statically imported variables), such as `id`, `label` and `key` (see [https://github.com/jbmusso/gremlin-javascript/issues/23](issue#23)). This is a TinkerPop3 Gremlin Server limitation. Workarounds: `vid`, `eid`, `userId`, etc.\n\n#### (String, Object) signature\n\n```javascript\nconst client = Gremlin.createClient();\n\nclient.execute('g.v(vid)', { vid: 1 }, (err, results) => {\n  console.log(results[0]) // notice how results is always an array\n});\n```\n\n#### (Object) signature\n\nExpects an `Object` as first argument with a `gremlin` property holding a `String` and a `bindings` property holding an `Object` of bound parameters.\n\n```javascript\nconst client = Gremlin.createClient();\nconst query = {\n  gremlin: 'g.V(vid)',\n  bindings: {\n    vid: 1\n  }\n}\n\nclient.execute(query, (err, results) => {\n  console.log(results[0])\n});\n```\n\n### Overriding low level settings on a per request basis\n\nFor advanced usage, for example if you wish to set the `op` or `processor` values for a given request only, you may wish to override the client level settings in the raw message sent to Gremlin Server:\n\n```javascript\nclient.execute('g.v(1)', null, { args: { language: 'nashorn' }}, (err, results) => {\n  // Handle result\n});\n```\nBasically, all you have to do is provide an Object as third parameter to any `client.stream()`, `client.execute()` or `client.streamMessage()` methods.\n\nBecause we're not sending any bound parameters (`bindings`) in this example, notice how the second argument **must** be set to `null` so the low level message object is not mistaken with bound arguments.\n\nIf you wish to also send bound parameters while overriding the low level message, you can do the following:\n\n```javascript\nclient.execute('g.v(vid)', { vid: 1 }, { args: { language: 'nashorn' }}, (err, results) => {\n  // Handle err and results\n});\n```\n\nOr in stream mode:\n```javascript\nclient.stream('g.v(vid)', { vid: 1 }, { args: { language: 'nashorn' }})\n  .pipe(/* ... */);\n```\n\n### Gremlin.bindForClient()\n\nGiven a map of functions returning query `Object`s (`{ gremlin, bindings }`), returns a map of function promising execution of these queries with the given Gremlin client.\n\nThis function is especially useful when used with [gremlin-loader](https://github.com/jbmusso/gremlin-loader), a Webpack loader which imports functions from `.groovy` files as `Object<String, Functions>` where each functions returns query `Object`s that need to be executed with a client.\n\n```javascript\nimport { bindForClient, createClient } from 'gremlin';\n\n// A function returning a Gremlin query object { gremlin, bindings }\nconst getByName = (name) => ({\n  gremlin: 'g.V().has(\"name\", name)',\n  bindings: { name }\n});\n\nconst client = createClient();\nconst queries = bindForClient(client, { getByName });\n\n// Then, within an async function:\nconst users = await queries.getByName('Alice');\n```\n\n### Using Gremlin-JavaScript syntax with Nashorn\n\nPlease see [/docs/UsingNashorn.md](Using Nashorn).\n\n## Running the Examples\n\nStart your own Gremlin Server with the default TinkerPop graph loaded by using `scripts: [scripts/generate-classic.groovy]` in your `gremlin-server.yaml` config file.\n\n### Node.js\n\nTo run the command line example:\n```shell\nnpm run examples:node\n```\n\n### Browser\n\nBuild library:\n```shell\nnpm run build:umd\n```\n\nStart the example server (listens on port 3000):\n```\nnpm run examples:browser\n```\n\nOpen [http://localhost:3000/examples/gremlin.html](http://localhost:3000/examples/gremlin.html) for an example on how a list of six vertices is being populated as the vertices are being streamed down from Gremlin Server.\n\n## To do list\n\n* better error handling\n* emit more client events\n* reconnect WebSocket if connection is lost\n* add option for secure WebSocket\n* more tests\n* performance optimization\n\n## License\n\nMIT(LICENSE)\n","readmeFilename":"README.md","description":"JavaScript client for TinkerPop3 Gremlin Server","homepage":"https://github.com/jbmusso/gremlin-javascript","keywords":["tinkerpop","gremlin","graphdb","graph","database"],"repository":{"type":"git","url":"git+https://github.com/jbmusso/gremlin-javascript.git"},"author":{"name":"Jean-Baptiste Musso","email":"jbmusso+github@gmail.com"},"bugs":{"url":"https://github.com/jbmusso/gremlin-javascript/issues"},"license":"MIT"}