diff --git a/.ci/doc/config.yml b/.ci/doc/config.yml new file mode 100644 index 000000000..4dc83e7d8 --- /dev/null +++ b/.ci/doc/config.yml @@ -0,0 +1,47 @@ +--- + +snippets: + mount: /mnt + path: doc/**/snippets/*.test.yml + templates: /mnt/.ci/doc/templates + +runners: + default: node + + node: + service: doc-runner-node + path: /var/snippets/node + lint: + global: true + cmd: eslint -c /mnt/.ci/doc/eslint.json {{ snippet.dir }} + before: timeout -t 600 ash -c 'until stat /tmp/runner_ready_to_lint; do sleep 1; done' + run: + cmd: node {{ snippet.source }} + before: timeout -t 600 ash -c 'until stat /tmp/runner_is_ready && curl -f -s -o /dev/null http://kuzzle:7512/_now; do sleep 1; done' + + web: + service: doc-runner-web + path: /var/snippets/web + lint: + global: true + cmd: eslint -c /mnt/.ci/doc/eslint.json {{ snippet.dir }}/*.html + before: timeout 600 bash -c 'until stat /tmp/runner_ready_to_lint; do sleep 1; done' + run: + cmd: node puppeteer.js {{ snippet.dir }}/{{ snippet.source }} + before: timeout 600 bash -c 'until stat /tmp/runner_is_ready && curl -f -s -o /dev/null http://kuzzle:7512/_now; do sleep 1; done' + + webpack: + service: doc-runner-webpack + path: /var/snippets/webpack + lint: + global: true + cmd: eslint -c /mnt/.ci/doc/eslint.json {{ snippet.dir }} + before: timeout 600 bash -c 'until stat /tmp/runner_ready_to_lint; do sleep 1; done' + build: + cmd: node webpackBuild.js {{ snippet.dir }}/{{ snippet.source }} + before: timeout 600 bash -c 'until stat /tmp/runner_is_ready; do sleep 1; done' + run: + cmd: node puppeteer.js /tmp/{{ snippet.name }}/index.html + before: timeout 600 bash -c 'until curl -f -s -o /dev/null http://kuzzle:7512/_now; do sleep 1; done' + + diff --git a/.ci/doc/docker-compose.yml b/.ci/doc/docker-compose.yml new file mode 100644 index 000000000..d6e1c083e --- /dev/null +++ b/.ci/doc/docker-compose.yml @@ -0,0 +1,138 @@ +version: '3' + +services: + kuzzle: + image: kuzzleio/kuzzle + ports: + - '7512:7512' + cap_add: + - SYS_PTRACE + depends_on: + - redis + - elasticsearch + container_name: kuzzle + environment: + - kuzzle_services__db__client__host=http://elasticsearch:9200 + - kuzzle_services__internalCache__node__host=redis + - kuzzle_services__memoryStorage__node__host=redis + - NODE_ENV=production + + redis: + image: redis:3.2 + + elasticsearch: + image: kuzzleio/elasticsearch:5.6.10 + ulimits: + nofile: 65536 + environment: + - cluster.name=kuzzle + - 'ES_JAVA_OPTS=-Xms256m -Xmx256m' + + doc-tests: + image: kuzzleio/snippets-tests + privileged: true + ports: + - '9229:9229' + depends_on: + - kuzzle + - doc-runner-node + - doc-runner-web + - doc-runner-webpack + volumes: + - ../..:/mnt + - /var/run/docker.sock:/var/run/docker.sock + - snippets:/var/snippets + environment: + - CONFIG_FILE=/mnt/.ci/doc/config.yml + + doc-runner-node: + image: node:10-alpine + volumes: + - ../..:/mnt + - snippets:/var/snippets + command: > + ash -c ' + mkdir -p /var/snippets/node; + apk add --no-cache curl; + npm install -g eslint; + cd /var/snippets/node; + npm install \ + bluebird \ + /mnt/ \ + eslint \ + eslint-plugin-html \ + eslint-plugin-import \ + eslint-plugin-node \ + eslint-plugin-promise \ + eslint-plugin-standard; + touch /tmp/runner_ready_to_lint; + touch /tmp/runner_is_ready; + tail -f /dev/null + ' + + doc-runner-web: + image: buildkite/puppeteer:latest + command: > + bash -c ' + mkdir -p /var/snippets/web; + apt-get update; + apt-get install -y curl; + npm install -g \ + eslint; + cd /mnt; + npm install; + cd /var/snippets/web; + cp /mnt/.ci/doc/puppeteer.js /var/snippets/web/; + npm install \ + /mnt/ \ + puppeteer \ + eslint \ + eslint-plugin-html \ + eslint-plugin-import \ + eslint-plugin-node \ + eslint-plugin-promise \ + eslint-plugin-standard; + touch /tmp/runner_ready_to_lint; + touch /tmp/runner_is_ready; + tail -f /dev/null + ' + volumes: + - ../..:/mnt + - snippets:/var/snippets + + doc-runner-webpack: + image: buildkite/puppeteer:latest + command: > + bash -c ' + mkdir -p /var/snippets/webpack; + apt-get update; + apt-get install -y curl; + npm install -g \ + eslint; + cd /var/snippets/webpack; + cp /mnt/.ci/doc/puppeteer.js /var/snippets/webpack/; + cp /mnt/.ci/doc/webpackBuild.js /var/snippets/webpack/; + npm install \ + /mnt/ \ + babel-loader \ + @babel/core \ + puppeteer \ + html-webpack-plugin \ + webpack \ + webpack-cli \ + eslint \ + eslint-plugin-html \ + eslint-plugin-import \ + eslint-plugin-node \ + eslint-plugin-promise \ + eslint-plugin-standard; + touch /tmp/runner_ready_to_lint; + touch /tmp/runner_is_ready; + tail -f /dev/null + ' + volumes: + - ../..:/mnt + - snippets:/var/snippets + +volumes: + snippets: diff --git a/.ci/doc/eslint.json b/.ci/doc/eslint.json new file mode 100644 index 000000000..3424a4451 --- /dev/null +++ b/.ci/doc/eslint.json @@ -0,0 +1,236 @@ +{ + "parserOptions": { + "ecmaVersion": 9, + "ecmaFeatures": { + "jsx": true + }, + "sourceType": "module" + }, + + "env": { + "es6": true, + "node": true, + "browser": true + }, + + "plugins": ["import", "node", "promise", "standard", "html"], + + "globals": { + "document": false, + "navigator": false, + "window": false, + "KuzzleSDK": true + }, + + "rules": { + "accessor-pairs": "error", + "arrow-spacing": ["error", { "before": true, "after": true }], + "block-spacing": ["error", "always"], + "brace-style": ["error", "1tbs", { "allowSingleLine": true }], + "camelcase": ["error", { "properties": "never" }], + "comma-dangle": [ + "error", + { + "arrays": "never", + "objects": "never", + "imports": "never", + "exports": "never", + "functions": "never" + } + ], + "comma-spacing": ["error", { "before": false, "after": true }], + "comma-style": ["error", "last"], + "constructor-super": "error", + "curly": ["error", "multi-line"], + "dot-location": ["error", "property"], + "eol-last": "error", + "eqeqeq": ["error", "always", { "null": "ignore" }], + "func-call-spacing": ["error", "never"], + "generator-star-spacing": ["error", { "before": true, "after": true }], + "handle-callback-err": ["error", "^(err|error)$"], + "indent": [ + "error", + 2, + { + "SwitchCase": 1, + "VariableDeclarator": 1, + "outerIIFEBody": 1, + "MemberExpression": 1, + "FunctionDeclaration": { "parameters": 1, "body": 1 }, + "FunctionExpression": { "parameters": 1, "body": 1 }, + "CallExpression": { "arguments": 1 }, + "ArrayExpression": 1, + "ObjectExpression": 1, + "ImportDeclaration": 1, + "flatTernaryExpressions": false, + "ignoreComments": false + } + ], + "key-spacing": ["error", { "beforeColon": false, "afterColon": true }], + "keyword-spacing": ["error", { "before": true, "after": true }], + "new-cap": ["error", { "newIsCap": true, "capIsNew": false }], + "new-parens": "error", + "no-array-constructor": "error", + "no-caller": "error", + "no-class-assign": "error", + "no-compare-neg-zero": "error", + "no-cond-assign": "error", + "no-const-assign": "error", + "no-constant-condition": ["error", { "checkLoops": false }], + "no-control-regex": "error", + "no-debugger": "error", + "no-delete-var": "error", + "no-dupe-args": "error", + "no-dupe-class-members": "error", + "no-dupe-keys": "error", + "no-duplicate-case": "error", + "no-empty-character-class": "error", + "no-empty-pattern": "error", + "no-eval": "error", + "no-ex-assign": "error", + "no-extend-native": "error", + "no-extra-bind": "error", + "no-extra-boolean-cast": "error", + "no-extra-parens": ["error", "functions"], + "no-fallthrough": "error", + "no-floating-decimal": "error", + "no-func-assign": "error", + "no-global-assign": "error", + "no-implied-eval": "error", + "no-inner-declarations": ["error", "functions"], + "no-invalid-regexp": "error", + "no-irregular-whitespace": "error", + "no-iterator": "error", + "no-label-var": "error", + "no-labels": ["error", { "allowLoop": false, "allowSwitch": false }], + "no-lone-blocks": "error", + "no-mixed-operators": [ + "error", + { + "groups": [ + ["==", "!=", "===", "!==", ">", ">=", "<", "<="], + ["&&", "||"], + ["in", "instanceof"] + ], + "allowSamePrecedence": true + } + ], + "no-mixed-spaces-and-tabs": "error", + "no-multi-spaces": "error", + "no-multi-str": "error", + "no-multiple-empty-lines": ["error", { "max": 1, "maxEOF": 0 }], + "no-negated-in-lhs": "error", + "no-new": "error", + "no-new-func": "error", + "no-new-object": "error", + "no-new-require": "error", + "no-new-symbol": "error", + "no-new-wrappers": "error", + "no-obj-calls": "error", + "no-octal": "error", + "no-octal-escape": "error", + "no-path-concat": "error", + "no-proto": "error", + "no-redeclare": "error", + "no-regex-spaces": "error", + "no-return-assign": ["error", "except-parens"], + "no-return-await": "error", + "no-self-assign": "error", + "no-self-compare": "error", + "no-sequences": "error", + "no-shadow-restricted-names": "error", + "no-sparse-arrays": "error", + "no-tabs": "error", + "no-template-curly-in-string": "error", + "no-this-before-super": "error", + "no-throw-literal": "error", + "no-trailing-spaces": "error", + "no-undef": "error", + "no-undef-init": "error", + "no-unexpected-multiline": "error", + "no-unmodified-loop-condition": "error", + "no-unneeded-ternary": ["error", { "defaultAssignment": false }], + "no-unreachable": "error", + "no-unsafe-finally": "error", + "no-unsafe-negation": "error", + "no-unused-expressions": [ + "error", + { + "allowShortCircuit": true, + "allowTernary": true, + "allowTaggedTemplates": true + } + ], + "no-use-before-define": [ + "error", + { "functions": false, "classes": false, "variables": false } + ], + "no-useless-call": "error", + "no-useless-computed-key": "error", + "no-useless-constructor": "error", + "no-useless-escape": "error", + "no-useless-rename": "error", + "no-useless-return": "error", + "no-whitespace-before-property": "error", + "no-with": "error", + "object-property-newline": [ + "error", + { "allowMultiplePropertiesPerLine": true } + ], + "one-var": ["error", { "initialized": "never" }], + "operator-linebreak": [ + "error", + "after", + { "overrides": { "?": "before", ":": "before" } } + ], + "prefer-promise-reject-errors": "error", + "quotes": [ + "error", + "single", + { "avoidEscape": true, "allowTemplateLiterals": true } + ], + "rest-spread-spacing": ["error", "never"], + "semi-spacing": ["error", { "before": false, "after": true }], + "space-before-blocks": ["error", "always"], + "space-before-function-paren": ["error", "always"], + "space-in-parens": ["error", "never"], + "space-infix-ops": "error", + "space-unary-ops": ["error", { "words": true, "nonwords": false }], + "spaced-comment": [ + "error", + "always", + { + "line": { "markers": ["*package", "!", "/", ",", "="] }, + "block": { + "balanced": true, + "markers": ["*package", "!", ",", ":", "::", "flow-include"], + "exceptions": ["*"] + } + } + ], + "symbol-description": "error", + "template-curly-spacing": ["error", "never"], + "template-tag-spacing": ["error", "never"], + "unicode-bom": ["error", "never"], + "use-isnan": "error", + "valid-typeof": ["error", { "requireStringLiterals": true }], + "wrap-iife": ["error", "any", { "functionPrototypeMethods": true }], + "yield-star-spacing": ["error", "both"], + "yoda": ["error", "never"], + + "import/export": "error", + "import/first": "error", + "import/no-duplicates": "error", + "import/no-webpack-loader-syntax": "error", + + "node/no-deprecated-api": "error", + "node/process-exit-as-throw": "error", + + "promise/param-names": "error", + + "standard/array-bracket-even-spacing": ["error", "either"], + "standard/computed-property-even-spacing": ["error", "even"], + "standard/no-callback-literal": "error", + "standard/object-curly-even-spacing": ["error", "either"] + } +} diff --git a/.ci/doc/puppeteer.js b/.ci/doc/puppeteer.js new file mode 100644 index 000000000..6e7ef84b1 --- /dev/null +++ b/.ci/doc/puppeteer.js @@ -0,0 +1,38 @@ +const puppeteer = require('puppeteer'); +const renderedSnippetPath = process.argv[2]; + +const runInBrowser = async snippetPath => { + let browser; + + try { + browser = await puppeteer.launch({ + dumpio: true, + args: ['--no-sandbox'] + }); + } catch (error) { + console.error(error); + return; + } + + try { + const page = await browser.newPage(); + + page.on('error', err => { + console.error(err); + }); + + page.on('pageerror', err => { + console.error(err); + }); + + await page.goto(`file:${snippetPath}`, { + waitUntil: 'networkidle0' + }); + } catch (error) { + console.error(error); + } finally { + await browser.close(); + } +}; + +runInBrowser(renderedSnippetPath); diff --git a/.ci/doc/templates/blank.tpl.js b/.ci/doc/templates/blank.tpl.js new file mode 100644 index 000000000..351ecaebe --- /dev/null +++ b/.ci/doc/templates/blank.tpl.js @@ -0,0 +1,14 @@ +// load the Kuzzle SDK module +const + { + Kuzzle, + WebSocket, + Http + } = require('kuzzle-sdk'); + +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); + +[snippet-code] +console.log('Everything is ok'); diff --git a/.ci/doc/templates/catch.tpl.js b/.ci/doc/templates/catch.tpl.js new file mode 100644 index 000000000..888ecdc2a --- /dev/null +++ b/.ci/doc/templates/catch.tpl.js @@ -0,0 +1,31 @@ +// Loads the Kuzzle SDK module and the websocket protocol +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client +const + kuzzle = new Kuzzle( + new WebSocket('kuzzle', { autoReconnect: false }) + ); + +// Adds a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error.message}`); +}); + +(async () => { + try { + await kuzzle.connect(); + } catch (error) { + console.log(`Can not connect to Kuzzle: ${error.message}`); + } + try { + [snippet-code] + } catch (e) { + console.log('Success'); + } finally { + kuzzle.disconnect(); + } +})(); diff --git a/.ci/doc/templates/controller.tpl.js b/.ci/doc/templates/controller.tpl.js new file mode 100644 index 000000000..17a2ff24e --- /dev/null +++ b/.ci/doc/templates/controller.tpl.js @@ -0,0 +1,11 @@ +// load the Kuzzle SDK module +const + { + Kuzzle, + WebSocket, + BaseController + } = require('kuzzle-sdk'); + +BaseController.prototype.query = () => Promise.resolve(null); + +[snippet-code] diff --git a/.ci/doc/templates/createDocumentAfterSnippet.tpl.js b/.ci/doc/templates/createDocumentAfterSnippet.tpl.js new file mode 100644 index 000000000..4327ab128 --- /dev/null +++ b/.ci/doc/templates/createDocumentAfterSnippet.tpl.js @@ -0,0 +1,27 @@ +// This template imports the snippet and then creates a document in the +// 'yellow-taxi collection in the `nyc-open-data` index. + +[snippet-code] + +// Require a kuzzle instance assigning it to a weird variable to avoid collisions and create the instance. +const $k = require('kuzzle-sdk'); +const $kInstance = new $k.Kuzzle(new $k.WebSocket('kuzzle')); + +// add a listener to detect any connection problems +$kInstance.on('networkError', error => { + console.error(`[doItAndCreateDocument.tpl] Network Error: ${error}`); +}); + +$kInstance.connect().then(() => { + const driver = { + name: 'Sirkis', + birthday: '1959-06-22', + license: 'B' + }; + + return $kInstance.document.create('nyc-open-data', 'yellow-taxi', driver); +}).catch(error => { + console.error(`[doItAndCreateDocument.tpl] Error creating document: ${error}`); +}).finally(() => { + $kInstance.disconnect(); +}); diff --git a/.ci/doc/templates/default.tpl.html b/.ci/doc/templates/default.tpl.html new file mode 100644 index 000000000..e19296a86 --- /dev/null +++ b/.ci/doc/templates/default.tpl.html @@ -0,0 +1,12 @@ + + + + + + Snippet testing + + + + [snippet-code] + + diff --git a/.ci/doc/templates/default.tpl.js b/.ci/doc/templates/default.tpl.js new file mode 100644 index 000000000..116a1203e --- /dev/null +++ b/.ci/doc/templates/default.tpl.js @@ -0,0 +1,27 @@ +// Loads the Kuzzle SDK module and the websocket protocol +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client +const + kuzzle = new Kuzzle( + new WebSocket('kuzzle', { autoReconnect: false }) + ); + +// Adds a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error.message}`); +}); + +(async () => { + try { + await kuzzle.connect(); + } catch (error) { + console.log(`Can not connect to Kuzzle: ${error.message}`); + } + [snippet-code] finally { + kuzzle.disconnect(); + } +})(); diff --git a/.ci/doc/templates/doIt.tpl.js b/.ci/doc/templates/doIt.tpl.js new file mode 100644 index 000000000..9194dec7a --- /dev/null +++ b/.ci/doc/templates/doIt.tpl.js @@ -0,0 +1,5 @@ +// This template expects a snippet that declares a function called doIt function +// which it calls. +[snippet-code] + +doIt(); diff --git a/.ci/doc/templates/empty-realtime.tpl.js b/.ci/doc/templates/empty-realtime.tpl.js new file mode 100644 index 000000000..f8139c144 --- /dev/null +++ b/.ci/doc/templates/empty-realtime.tpl.js @@ -0,0 +1,23 @@ +function sleep (ms, i = 0) { + setTimeout(() => { + if (i >= 150 || outputs.length > 0) { + console.log = consoleLog; + console.log(...outputs); + + // force exit: do not wait for the event loop to be empty + process.exit(0); + } + sleep(ms, ++i); + }, ms); +} + +const consoleLog = console.log; +const outputs = []; + +console.log = (...args) => { + outputs.push(...args); +}; + +[snippet-code] + +sleep(200); diff --git a/.ci/doc/templates/empty.tpl.js b/.ci/doc/templates/empty.tpl.js new file mode 100644 index 000000000..3da052031 --- /dev/null +++ b/.ci/doc/templates/empty.tpl.js @@ -0,0 +1,3 @@ +[snippet-code] + +console.log('Success'); diff --git a/.ci/doc/templates/eventemitter.tpl.js b/.ci/doc/templates/eventemitter.tpl.js new file mode 100644 index 000000000..df1a48f9f --- /dev/null +++ b/.ci/doc/templates/eventemitter.tpl.js @@ -0,0 +1,6 @@ +const + { + KuzzleEventEmitter + } = require('kuzzle-sdk'); + +[snippet-code] diff --git a/.ci/doc/templates/mqtt-end.tpl.js b/.ci/doc/templates/mqtt-end.tpl.js new file mode 100644 index 000000000..4b051836c --- /dev/null +++ b/.ci/doc/templates/mqtt-end.tpl.js @@ -0,0 +1,4 @@ +[snippet-code] finally { + console.log('Success'); + client.end(); +} diff --git a/.ci/doc/templates/realtime.tpl.js b/.ci/doc/templates/realtime.tpl.js new file mode 100644 index 000000000..2ef73a8b6 --- /dev/null +++ b/.ci/doc/templates/realtime.tpl.js @@ -0,0 +1,47 @@ +// Loads the Kuzzle SDK module and the websocket protocol +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client +const + kuzzle = new Kuzzle( + new WebSocket('kuzzle', { autoReconnect: false }) + ); + +// Adds a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error.message}`); +}); + +function sleep (ms) { + return new Promise(resolve => setTimeout(resolve, ms)); +} + +(async () => { + try { + await kuzzle.connect(); + } catch (error) { + console.log(`Cannot connect to Kuzzle: ${error.message}`); + } + + const consoleLog = console.log; + const outputs = []; + + console.log = (...args) => { + outputs.push(...args); + }; + + [snippet-code] finally { + for (let i = 150; i > 0 && outputs.length <= 0; --i) { + await sleep(200); + } + + console.log = consoleLog; + console.log(...outputs); + + // force exit: do not wait for the event loop to be empty + process.exit(0); + } +})(); diff --git a/.ci/doc/templates/success.tpl.js b/.ci/doc/templates/success.tpl.js new file mode 100644 index 000000000..a697cd07f --- /dev/null +++ b/.ci/doc/templates/success.tpl.js @@ -0,0 +1,32 @@ +// Loads the Kuzzle SDK module and the websocket protocol +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client +const + kuzzle = new Kuzzle( + new WebSocket('kuzzle', { autoReconnect: false }) + ); + +// Adds a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error.message}`); +}); + +(async function run () { + try { + await kuzzle.connect(); + } catch (error) { + console.log(`Can not connect to Kuzzle: ${error.message}`); + } + try { + [snippet-code] + console.log('Success'); + } catch (e) { + console.log(e); + } finally { + kuzzle.disconnect(); + } +})(); diff --git a/.ci/doc/templates/thencatch.tpl.js b/.ci/doc/templates/thencatch.tpl.js new file mode 100644 index 000000000..562702342 --- /dev/null +++ b/.ci/doc/templates/thencatch.tpl.js @@ -0,0 +1,28 @@ +const Bluebird = require('bluebird'); + +// Loads the Kuzzle SDK module and the websocket protocol +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client +const + kuzzle = new Kuzzle( + new WebSocket('kuzzle', { autoReconnect: false }) + ); + +// Adds a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error.message}`); +}); + +Bluebird.resolve( + kuzzle + .connect() + .then(() => { + return [snippet-code] + }) +) + .catch(() => 'nothing') + .finally(() => kuzzle.disconnect()); diff --git a/.ci/doc/templates/without-connect.tpl.js b/.ci/doc/templates/without-connect.tpl.js new file mode 100644 index 000000000..abd722bb2 --- /dev/null +++ b/.ci/doc/templates/without-connect.tpl.js @@ -0,0 +1,22 @@ +// Loads the Kuzzle SDK module and the websocket protocol +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client +const + kuzzle = new Kuzzle( + new WebSocket('kuzzle', { autoReconnect: false }) + ); + +// Adds a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error.message}`); +}); + +(async () => { + [snippet-code] finally { + kuzzle.disconnect(); + } +})(); diff --git a/.ci/doc/webpackBuild.js b/.ci/doc/webpackBuild.js new file mode 100644 index 000000000..72038a3c2 --- /dev/null +++ b/.ci/doc/webpackBuild.js @@ -0,0 +1,53 @@ +const path = require('path'); +const webpack = require('webpack'); +const HtmlWebpackPlugin = require('html-webpack-plugin'); + +const build = async file => { + const config = { + entry: file, + output: { + path: path.resolve('/tmp', path.basename(file).replace(/\.[^.]+$/, '')), + filename: 'build.js' + }, + module: { + rules: [ + { + test: /\.js$/, + loader: 'babel-loader' + } + ] + }, + devtool: 'eval-source-map', + plugins: [new HtmlWebpackPlugin()] + }; + + return new Promise((resolve, reject) => { + webpack(config, (err, stats) => { + if (err) { + if (err.details) { + return reject(err.details); + } + return reject(err.stack || err); + } + const info = stats.toJson(); + + if (stats.hasErrors()) { + return reject(info.errors); + } + + if (stats.hasWarnings()) { + return resolve(info.warnings); + } + resolve(true); + }); + }); +}; + +(async () => { + try { + await build(process.argv[2]); + } catch (e) { + console.error(e); + throw e; + } +})(); diff --git a/.ci/docker-compose.yml b/.ci/docker-compose.yml index 4e8befb88..50c1e4867 100644 --- a/.ci/docker-compose.yml +++ b/.ci/docker-compose.yml @@ -1,4 +1,4 @@ -version: '2' +version: '3' services: kuzzle: @@ -10,7 +10,6 @@ services: depends_on: - redis - elasticsearch - container_name: kuzzle environment: - kuzzle_services__db__client__host=http://elasticsearch:9200 - kuzzle_services__internalCache__node__host=redis @@ -21,9 +20,13 @@ services: image: redis:3.2 elasticsearch: - image: kuzzleio/elasticsearch:5.4.1 + image: kuzzleio/elasticsearch:5.6.10 ulimits: nofile: 65536 environment: - cluster.name=kuzzle - "ES_JAVA_OPTS=-Xms256m -Xmx256m" + +volumes: + snippets: + diff --git a/.travis.yml b/.travis.yml index ddace1a2e..03958bd10 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,6 +1,7 @@ jobs: include: - - stage: Tests + - name: Sdk tests + stage: Tests sudo: false language: node_js node_js: 8 @@ -32,6 +33,14 @@ jobs: after_success: - cat ./coverage/lcov.info | ./node_modules/.bin/codecov + - name: Documentation tests + stage: Tests + language: node_js + node_js: 8 + + script: + - docker-compose -f .ci/doc/docker-compose.yml run doc-tests node index + - stage: "Deploy Stable release on NPM" if: type != pull_request && branch = master sudo: false diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 000000000..a4b5bd3e9 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,14 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${workspaceFolder}/index.js" + } + ] +} \ No newline at end of file diff --git a/doc/6/controllers/auth/check-token/index.md b/doc/6/controllers/auth/check-token/index.md new file mode 100644 index 000000000..896cf22f4 --- /dev/null +++ b/doc/6/controllers/auth/check-token/index.md @@ -0,0 +1,38 @@ +--- +code: true +type: page +title: checkToken +description: Checks a JWT's validity. +--- + +# checkToken + +Checks a token validity. + +If no token is provided, the SDK checks its internal authentication token. + +
+ +```js +checkToken([token]); +``` + +
+ +| Property | Type | Description | +| -------- | ----------------- | ----------- | +| `token` | 
string
| Optional authentication token | + +## Resolves + +An `object` representing the token validity status + +| Name | Type | Description | +| ------------- | ------------------ | --------------------------------- | +| `valid` | 
boolean
| Tell if the token is valid or not | +| `state` | 
string
| Explain why the token is invalid | +|  `expires_at` | 
number
| Token expiration timestamp | + +## Usage + +<<< ./snippets/check-token.js diff --git a/doc/6/controllers/auth/check-token/snippets/check-token.js b/doc/6/controllers/auth/check-token/snippets/check-token.js new file mode 100644 index 000000000..44202a1c5 --- /dev/null +++ b/doc/6/controllers/auth/check-token/snippets/check-token.js @@ -0,0 +1,23 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + const jwt = await kuzzle.auth.login('local', credentials); + + // Check the internal jwt validity + await kuzzle.auth.checkToken(); + + // Check the jwt validity + const result = await kuzzle.auth.checkToken(jwt); + console.log(result); + /* + { valid: true, expiresAt: 1540824822897 } + */ + + if (result.valid) { + console.log('Token is valid'); + } else { + console.error(`Token is invalid: ${result.state}`); + } +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/check-token/snippets/check-token.test.yml b/doc/6/controllers/auth/check-token/snippets/check-token.test.yml new file mode 100644 index 000000000..1e603a0d7 --- /dev/null +++ b/doc/6/controllers/auth/check-token/snippets/check-token.test.yml @@ -0,0 +1,11 @@ +--- +name: auth#checkToken +description: Checks a JWT token's validity. +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Token is valid + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/create-my-credentials/index.md b/doc/6/controllers/auth/create-my-credentials/index.md new file mode 100644 index 000000000..57c5954ea --- /dev/null +++ b/doc/6/controllers/auth/create-my-credentials/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: createMyCredentials +description: Create the current user's credentials for the specified strategy. +--- + +# createMyCredentials + +Creates new credentials for the specified strategy for the current user. + +
+ +```js +createMyCredentials(strategy, credentials, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------- | ----------------- | --------------- | +| `strategy` | 
string
| Strategy to use | +| `credentials` | 
object
| New credentials | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +An `object` representing the new credentials. +The content depends on the authentication strategy. + +## Usage + +<<< ./snippets/create-my-credentials.js diff --git a/doc/6/controllers/auth/create-my-credentials/snippets/create-my-credentials.js b/doc/6/controllers/auth/create-my-credentials/snippets/create-my-credentials.js new file mode 100644 index 000000000..e2213a48c --- /dev/null +++ b/doc/6/controllers/auth/create-my-credentials/snippets/create-my-credentials.js @@ -0,0 +1,11 @@ +const credentials = { username: 'foo', password: 'bar' }; + +await kuzzle.auth.login('local', credentials); + +const response = await kuzzle.auth.createMyCredentials('other', credentials); +console.log(response); +/* + { username: 'foo', kuid: 'AVkDBl3YsT6qHI7MxLz0' } +*/ + +console.log('Credentials successfully created'); diff --git a/doc/6/controllers/auth/create-my-credentials/snippets/create-my-credentials.test.yml b/doc/6/controllers/auth/create-my-credentials/snippets/create-my-credentials.test.yml new file mode 100644 index 000000000..fe731bd48 --- /dev/null +++ b/doc/6/controllers/auth/create-my-credentials/snippets/create-my-credentials.test.yml @@ -0,0 +1,10 @@ +name: auth#createMyCredentials +description: Creates the current user's credentials for the specified strategy +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: catch +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/credentials-exist/index.md b/doc/6/controllers/auth/credentials-exist/index.md new file mode 100644 index 000000000..9c7d5c198 --- /dev/null +++ b/doc/6/controllers/auth/credentials-exist/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: credentialsExist +description: Check that the current user has credentials for the specified strategy +--- + +# credentialsExist + +Checks that the current authenticated user has credentials for the specified authentication strategy. + +
+ +```js +credentialsExist(strategy, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | --------------- | +| `local` | 
string
| Strategy to use | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to `true` if the credentials exist, `false` otherwise. + +## Usage + +<<< ./snippets/credentials-exist.js diff --git a/doc/6/controllers/auth/credentials-exist/snippets/credentials-exist.js b/doc/6/controllers/auth/credentials-exist/snippets/credentials-exist.js new file mode 100644 index 000000000..e194679cd --- /dev/null +++ b/doc/6/controllers/auth/credentials-exist/snippets/credentials-exist.js @@ -0,0 +1,13 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const exists = await kuzzle.auth.credentialsExist('local'); + + if (exists === true) { + console.log('Credentials exist'); + } +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/credentials-exist/snippets/credentials-exist.test.yml b/doc/6/controllers/auth/credentials-exist/snippets/credentials-exist.test.yml new file mode 100644 index 000000000..a1e62d66d --- /dev/null +++ b/doc/6/controllers/auth/credentials-exist/snippets/credentials-exist.test.yml @@ -0,0 +1,10 @@ +name: auth#credentialsExist +description: Checks a JWT token's validity. +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Credentials exist + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/delete-my-credentials/index.md b/doc/6/controllers/auth/delete-my-credentials/index.md new file mode 100644 index 000000000..a465a5b00 --- /dev/null +++ b/doc/6/controllers/auth/delete-my-credentials/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: deleteMyCredentials +description: Deletes credentials for a specific strategy, associated to the current user +--- + +# deleteMyCredentials + +Deletes credentials for a specific strategy associated to the current user. + +Deleting credantials, doesn't revoke existing/active JWT tokens. + +If the credentials that generated the current JWT are removed, the user will remain logged in until they log out or their session expire. After that, they will no longer be able to log in with the deleted credentials. + +
+ +```js +deleteMyCredentials(strategy, [options]); +``` + +
+ +| Arguments | Type | Description | +| ---------- | ----------------- | --------------- | +| `strategy` | 
string
| Strategy to use | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +A `boolean` indicating if the credentials are being deleted. + +## Usage + +<<< ./snippets/delete-my-credentials.js diff --git a/doc/6/controllers/auth/delete-my-credentials/snippets/delete-my-credentials.js b/doc/6/controllers/auth/delete-my-credentials/snippets/delete-my-credentials.js new file mode 100644 index 000000000..fc0ac408b --- /dev/null +++ b/doc/6/controllers/auth/delete-my-credentials/snippets/delete-my-credentials.js @@ -0,0 +1,13 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const success = await kuzzle.auth.deleteMyCredentials('local'); + console.log(success); + if (success === true) { + console.log('Credentials successfully deleted'); + } +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/delete-my-credentials/snippets/delete-my-credentials.test.yml b/doc/6/controllers/auth/delete-my-credentials/snippets/delete-my-credentials.test.yml new file mode 100644 index 000000000..2b5b741ae --- /dev/null +++ b/doc/6/controllers/auth/delete-my-credentials/snippets/delete-my-credentials.test.yml @@ -0,0 +1,10 @@ +name: auth#deleteMyCredentials +description: Deletes the current user's credentials for the specified strategy +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Credentials successfully deleted + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/get-current-user/index.md b/doc/6/controllers/auth/get-current-user/index.md new file mode 100644 index 000000000..d7cec9938 --- /dev/null +++ b/doc/6/controllers/auth/get-current-user/index.md @@ -0,0 +1,38 @@ +--- +code: true +type: page +title: getCurrentUser +description: Returns the profile object for the user linked to the json web token +--- + +# getCurrentUser + +Returns information about the currently logged in user. + +
+ +```js +getCurrentUser([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +A [User](/sdk/js/6/core-classes/user) representing the current user logged with the SDK. + +## Usage + +<<< ./snippets/get-current-user.js diff --git a/doc/6/controllers/auth/get-current-user/snippets/get-current-user.js b/doc/6/controllers/auth/get-current-user/snippets/get-current-user.js new file mode 100644 index 000000000..ee93620ed --- /dev/null +++ b/doc/6/controllers/auth/get-current-user/snippets/get-current-user.js @@ -0,0 +1,23 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const user = await kuzzle.auth.getCurrentUser(); + console.log(user); + /* + User { + _id: 'foo', + content: + { profileIds: [ 'default' ], + _kuzzle_info: + { author: '-1', + createdAt: 1540210776636, + updatedAt: null, + updater: null } } } + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/get-current-user/snippets/get-current-user.test.yml b/doc/6/controllers/auth/get-current-user/snippets/get-current-user.test.yml new file mode 100644 index 000000000..dc3dcf93f --- /dev/null +++ b/doc/6/controllers/auth/get-current-user/snippets/get-current-user.test.yml @@ -0,0 +1,10 @@ +name: auth#getCurrentUser +description: Returns the profile object for the user linked to the `json web token` +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/get-my-credentials/index.md b/doc/6/controllers/auth/get-my-credentials/index.md new file mode 100644 index 000000000..a5a4a3aef --- /dev/null +++ b/doc/6/controllers/auth/get-my-credentials/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: getMyCredentials +description: Returns the current user's credential information for the specified strategy. +--- + +# getMyCredentials + +Returns credentials information for the currently logged in user. + +The returned data depends on the given authentication strategy, and should never include any sensitive information. + +The result can be an empty object. + +
+ +```js +getMyCredentials(strategy, [options]); +``` + +
+ +| Arguments | Type | Description | +| ---------- | ----------------- | --------------- | +| `strategy` | 
string
| Strategy to use | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +An `object` representing the credentials for the provided authentication strategy. +Its content depends on the authentication strategy. + +## Usage + +<<< ./snippets/get-my-credentials.js diff --git a/doc/6/controllers/auth/get-my-credentials/snippets/get-my-credentials.js b/doc/6/controllers/auth/get-my-credentials/snippets/get-my-credentials.js new file mode 100644 index 000000000..9f6888f41 --- /dev/null +++ b/doc/6/controllers/auth/get-my-credentials/snippets/get-my-credentials.js @@ -0,0 +1,15 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const localCredentials = await kuzzle.auth.getMyCredentials('local'); + console.log(localCredentials); + /* + { username: 'foo', kuid: 'AVkDBl3YsT6qHI7MxLz0' } + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/get-my-credentials/snippets/get-my-credentials.test.yml b/doc/6/controllers/auth/get-my-credentials/snippets/get-my-credentials.test.yml new file mode 100644 index 000000000..e43b7ca38 --- /dev/null +++ b/doc/6/controllers/auth/get-my-credentials/snippets/get-my-credentials.test.yml @@ -0,0 +1,10 @@ +name: auth#getMyCredentials +description: Returns the current user's credential information for the specified ``. +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/get-my-rights/index.md b/doc/6/controllers/auth/get-my-rights/index.md new file mode 100644 index 000000000..f8fa73bdb --- /dev/null +++ b/doc/6/controllers/auth/get-my-rights/index.md @@ -0,0 +1,46 @@ +--- +code: true +type: page +title: getMyRights +description: Returns the rights for the user linked to the `JSON Web Token`. +--- + +# getMyRights + +Returns the exhaustive list of granted or denied rights for the currently logged in user. + +
+ +```js +getMyRights([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | --------------------------------- | +| `queuable` | 
boolean

(`true`) | Make this request queuable or not | + +## Resolves + +An `object[]` containing: + +| Property | Type | Description | +| ------------- | ----------------- | ------------------------------------------- | +| `controller` | 
string
| Controller on wich the rights are applied | +| `action` | 
string
| Action on wich the rights are applied | +| `index` | 
string
| Index on wich the rights are applied | +|  `collection` | 
string
| Collection on wich the rights are applied | +|  `value` | 
string
| Rights (`allowed`, `denied`, `conditional`) | + +## Usage + +<<< ./snippets/get-my-rights.js diff --git a/doc/6/controllers/auth/get-my-rights/snippets/get-my-rights.js b/doc/6/controllers/auth/get-my-rights/snippets/get-my-rights.js new file mode 100644 index 000000000..e61d723d6 --- /dev/null +++ b/doc/6/controllers/auth/get-my-rights/snippets/get-my-rights.js @@ -0,0 +1,19 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const rights = await kuzzle.auth.getMyRights(); + console.log(rights); + /* + [ { controller: '*', + action: '*', + collection: '*', + index: '*', + value: 'allowed' } ] + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/get-my-rights/snippets/get-my-rights.test.yml b/doc/6/controllers/auth/get-my-rights/snippets/get-my-rights.test.yml new file mode 100644 index 000000000..059f24813 --- /dev/null +++ b/doc/6/controllers/auth/get-my-rights/snippets/get-my-rights.test.yml @@ -0,0 +1,10 @@ +name: auth#getMyRights +description: Returns the rights for the user linked to the json web token +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/get-strategies/index.md b/doc/6/controllers/auth/get-strategies/index.md new file mode 100644 index 000000000..9581ee667 --- /dev/null +++ b/doc/6/controllers/auth/get-strategies/index.md @@ -0,0 +1,38 @@ +--- +code: true +type: page +title: getStrategies +description: Get all authentication strategies registered in Kuzzle. +--- + +# getStrategies + +Gets the exhaustive list of registered authentication strategies. + +
+ +```js +getStrategies([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type | Description | Default | +| ---------- | ------------------------------- | --------------------------------- | ------- | +| `queuable` | 
boolean

(`true`) | Make this request queuable or not | + +## Resolves + +An array of available strategies names. + +## Usage + +<<< ./snippets/get-strategies.js diff --git a/doc/6/controllers/auth/get-strategies/snippets/get-strategies.js b/doc/6/controllers/auth/get-strategies/snippets/get-strategies.js new file mode 100644 index 000000000..ad8cb4034 --- /dev/null +++ b/doc/6/controllers/auth/get-strategies/snippets/get-strategies.js @@ -0,0 +1,15 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const strategies = await kuzzle.auth.getStrategies(); + console.log(strategies); + /* + [ 'local', 'facebook' ] + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/get-strategies/snippets/get-strategies.test.yml b/doc/6/controllers/auth/get-strategies/snippets/get-strategies.test.yml new file mode 100644 index 000000000..993d67742 --- /dev/null +++ b/doc/6/controllers/auth/get-strategies/snippets/get-strategies.test.yml @@ -0,0 +1,10 @@ +name: auth#getStrategies +description: Get all authentication strategies registered in Kuzzle +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/index.md b/doc/6/controllers/auth/index.md new file mode 100644 index 000000000..f2c86af03 --- /dev/null +++ b/doc/6/controllers/auth/index.md @@ -0,0 +1,6 @@ +--- +code: true +type: branch +title: auth +description: auth controller documentation +--- diff --git a/doc/6/controllers/auth/login/index.md b/doc/6/controllers/auth/login/index.md new file mode 100644 index 000000000..22446d6b7 --- /dev/null +++ b/doc/6/controllers/auth/login/index.md @@ -0,0 +1,51 @@ +--- +code: true +type: page +title: login +description: Authenticate a user +--- + +# login + +Authenticates a user. + +If this action is successful, then the [jwt](/sdk/js/6/core-classes/kuzzle/properties) property of this class instance is set to the new authentication token. + +All further requests emitted by this SDK instance will be on behalf of the authenticated user, until either the authenticated token expires, the [logout](/sdk/js/6/controllers/auth/logout) action is called, or the `jwt` property is manually set to another value. + +## Arguments + +```js +login(strategy, [credentials], [expiresIn]); +``` + +
+ +| Arguments | Type | Description | +| ------------- | ----------------- | -------------------------------------------------------------------------------------- | +| `strategy` | 
string
| Name of the strategy to use | +| `credentials` | 
object
|  Credentials for the strategy | +| `expiresIn` | 
string
|  Expiration time in [ms library](https://www.npmjs.com/package/ms) format. (e.g. `2h`) | + +### strategy + +The name of the [authentication strategy](/core/1/guides/kuzzle-depth/authentication/) used to log the user in. + +Depending on the chosen authentication strategy, additional credential arguments may be required. +The API request example in this page provides the necessary arguments for the [`local` authentication plugin](https://github.com/kuzzleio/kuzzle-plugin-auth-passport-local). + +Check the appropriate [authentication plugin](/core/1/plugins/guides/strategies/overview/) documentation to get the list of additional arguments to provide. + +### expiresIn + + The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file](/core/1/guides/essentials/configuration/). + +## Resolves + +The **login** action returns the encrypted JSON Web Token. + +## Usage + +_Local strategy login example_ + +<<< ./snippets/login.js diff --git a/doc/6/controllers/auth/login/snippets/login.js b/doc/6/controllers/auth/login/snippets/login.js new file mode 100644 index 000000000..90d725579 --- /dev/null +++ b/doc/6/controllers/auth/login/snippets/login.js @@ -0,0 +1,12 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + const jwt = await kuzzle.auth.login('local', credentials); + console.log(jwt); + /* + 'eyJhbGciOiJIUzI1NiIsIkpXVCJ9.eyJfaWQiOiJmb28iLCJpYXQiOjE.wSPmb0z2tErRdYEg' + */ + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/login/snippets/login.test.yml b/doc/6/controllers/auth/login/snippets/login.test.yml new file mode 100644 index 000000000..8c986543f --- /dev/null +++ b/doc/6/controllers/auth/login/snippets/login.test.yml @@ -0,0 +1,11 @@ +--- +name: auth#login +description: Authenticate a user +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/logout/index.md b/doc/6/controllers/auth/logout/index.md new file mode 100644 index 000000000..42d67866c --- /dev/null +++ b/doc/6/controllers/auth/logout/index.md @@ -0,0 +1,24 @@ +--- +code: true +type: page +title: logout +description: Revokes the user's token & unsubscribe them from registered rooms. +--- + +# logout + +Revokes the current authentication token. + +If there were any, real-time subscriptions are cancelled. + +If this action is successful, then the [jwt](/sdk/js/6/core-classes/kuzzle/properties) property of this class instance is unset. + +
+ +```js +logout(); +``` + +## Usage + +<<< ./snippets/logout.js diff --git a/doc/6/controllers/auth/logout/snippets/logout.js b/doc/6/controllers/auth/logout/snippets/logout.js new file mode 100644 index 000000000..c5f06be4b --- /dev/null +++ b/doc/6/controllers/auth/logout/snippets/logout.js @@ -0,0 +1,11 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + await kuzzle.auth.logout(); + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/logout/snippets/logout.test.yml b/doc/6/controllers/auth/logout/snippets/logout.test.yml new file mode 100644 index 000000000..cf6a09c0e --- /dev/null +++ b/doc/6/controllers/auth/logout/snippets/logout.test.yml @@ -0,0 +1,10 @@ +name: auth#logout +description: Revokes the user's token & unsubscribe them from registered rooms. +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/refresh-token/index.md b/doc/6/controllers/auth/refresh-token/index.md new file mode 100644 index 000000000..a0b517989 --- /dev/null +++ b/doc/6/controllers/auth/refresh-token/index.md @@ -0,0 +1,58 @@ +--- +code: true +type: page +title: refreshToken +description: Refresh an authentication token +--- + +# refreshToken + + + +Refreshes a valid, non-expired authentication token. + +If this action is successful, then the [jwt](/sdk/js/6/core-classes/kuzzle/properties) property of this class instance is set to the new authentication token. + +All further requests emitted by this SDK instance will be on behalf of the authenticated user, until either the authenticated token expires, the [logout](/sdk/js/6/controllers/auth/logout) action is called, or the `jwt` property is manually set to another value. + + +## Arguments + +```js +refreshToken ([options]) +``` + +
+ +| Arguments | Type | Description | +|--------------|---------|-------------| +| `options` | 
object
| Query options | + + +### options + +Additional query options + +| Property | Type
(default) | Description | +| -------------- | --------- | ------------- | +| `expiresIn` | 
string
| Expiration time in [ms library](https://www.npmjs.com/package/ms) format. (e.g. `2h`) | +| `queuable` | 
boolean

(`true`)| If true, queues the request during downtime, until connected to Kuzzle again | + +### expiresIn + +The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file](/core/1/guides/essentials/configuration/). + +## Resolves + +The `refreshToken` action resolves to a token object with the following properties: + +| Property | Type | Description | +|--------------|---------|-------------| +| `_id` | 
string
| User unique identifier ([kuid](/core/1/guides/essentials/user-authentication/#kuzzle-user-identifier-kuid)) | +| `expiresAt` | 
number
| Expiration timestamp in Epoch-millis format (UTC) | +| `jwt` | 
string
| Authentication token | +| `ttl` | 
number
| Time to live of the authentication token, in milliseconds | + +## Usage + +<<< ./snippets/refreshToken.js diff --git a/doc/6/controllers/auth/refresh-token/snippets/refreshToken.js b/doc/6/controllers/auth/refresh-token/snippets/refreshToken.js new file mode 100644 index 000000000..778869426 --- /dev/null +++ b/doc/6/controllers/auth/refresh-token/snippets/refreshToken.js @@ -0,0 +1,22 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + const jwt = await kuzzle.auth.login('local', credentials); + + // Prints the encrypted authentication token + console.log(jwt); + + // Note: to get a different token, you actually need to wait at least + // 1 second. Otherwise you do receive a refreshed token, but with the exact + // same caracteristics, as the key depends on the timestamp in Epoch format + await new Promise(resolve => setTimeout(resolve, 1000)); + + // Prints: + // { _id: '', + // jwt: '' + // expiresAt: 1553185334220, + // ttl: 3600000 } + console.log(await kuzzle.auth.refreshToken()); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/refresh-token/snippets/refreshToken.test.yml b/doc/6/controllers/auth/refresh-token/snippets/refreshToken.test.yml new file mode 100644 index 000000000..be2ec825c --- /dev/null +++ b/doc/6/controllers/auth/refresh-token/snippets/refreshToken.test.yml @@ -0,0 +1,15 @@ +--- +name: auth#refreshtoken +description: Refresh a user's token +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: + - ^.*\..*$ + - ^{ _id: 'foo' + - ^\s*jwt: '.*\..*' + - ^\s*expiresAt: \d+ + - ^\s*ttl: \d+ } +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/update-my-credentials/index.md b/doc/6/controllers/auth/update-my-credentials/index.md new file mode 100644 index 000000000..06bf649ec --- /dev/null +++ b/doc/6/controllers/auth/update-my-credentials/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: updateMyCredentials +description: Update the current user's credentials for the specified strategy. +--- + +# updateMyCredentials + +Updates the credentials of the currently logged in user for the specified strategy. + +
+ +```js +updateMyCredentials(strategy, credentials, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------- | ----------------- | --------------- | +| `strategy` | 
string
| Strategy to use | +| `credentials` | 
object
| New credentials | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +An `object` representing the new credentials. +The content depends on the authentication strategy. + +## Usage + +<<< ./snippets/update-my-credentials.js diff --git a/doc/6/controllers/auth/update-my-credentials/snippets/update-my-credentials.js b/doc/6/controllers/auth/update-my-credentials/snippets/update-my-credentials.js new file mode 100644 index 000000000..faa96bf0c --- /dev/null +++ b/doc/6/controllers/auth/update-my-credentials/snippets/update-my-credentials.js @@ -0,0 +1,18 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const response = await kuzzle.auth.updateMyCredentials( + 'local', + { password: 'worakls' } + ); + console.log(response); + /* + { username: 'foo' } + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/update-my-credentials/snippets/update-my-credentials.test.yml b/doc/6/controllers/auth/update-my-credentials/snippets/update-my-credentials.test.yml new file mode 100644 index 000000000..43f5545c9 --- /dev/null +++ b/doc/6/controllers/auth/update-my-credentials/snippets/update-my-credentials.test.yml @@ -0,0 +1,10 @@ +name: auth#updateMyCredentials +description: Update the current user's credentials for the specified ``. +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/update-self/index.md b/doc/6/controllers/auth/update-self/index.md new file mode 100644 index 000000000..3a041ecd7 --- /dev/null +++ b/doc/6/controllers/auth/update-self/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: updateSelf +description: Updates the current user object in Kuzzle. +--- + +# updateSelf + +Updates the currently logged in user content. + +This route cannot update the list of associated security profiles. To change a user's security profiles, the route [security:updateUser](/core/1/api/controllers/security/update-user/) must be used instead. + +
+ +```js +updateSelf(content, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ----------------------- | +| `content` | 
object
| User custom information | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +A [User](/sdk/js/6/core-classes/user) representing the current user logged with the SDK. + +## Usage + +<<< ./snippets/update-self.js diff --git a/doc/6/controllers/auth/update-self/snippets/update-self.js b/doc/6/controllers/auth/update-self/snippets/update-self.js new file mode 100644 index 000000000..9be64a2da --- /dev/null +++ b/doc/6/controllers/auth/update-self/snippets/update-self.js @@ -0,0 +1,24 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const user = await kuzzle.auth.updateSelf({ hungry: 'music' }); + console.log(user); + /* + User { + _id: 'foo', + content: + { profileIds: [ 'default' ], + hungry: 'music', + _kuzzle_info: + { author: '-1', + createdAt: 1540210776636, + updatedAt: null, + updater: null } } } + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/update-self/snippets/update-self.test.yml b/doc/6/controllers/auth/update-self/snippets/update-self.test.yml new file mode 100644 index 000000000..ac9007638 --- /dev/null +++ b/doc/6/controllers/auth/update-self/snippets/update-self.test.yml @@ -0,0 +1,10 @@ +name: auth#updateSelf +description: Updates the current user object in Kuzzle +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/auth/validate-my-credentials/index.md b/doc/6/controllers/auth/validate-my-credentials/index.md new file mode 100644 index 000000000..5ebcda913 --- /dev/null +++ b/doc/6/controllers/auth/validate-my-credentials/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: validateMyCredentials +description: Validate the current user's credentials for the specified strategy. +--- + +# validateMyCredentials + +Validates the provided credentials against a specified authentication strategy. + +This route neither creates nor modifies credentials. + +
+ +```js +validateMyCredentials(strategy, [credentials], [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------- | ----------------- | --------------- | +| `strategy` | 
string
| Strategy to use | +| `credentials` | 
object
| Credentials | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to `true` if the credentials are valid, `false` otherwise. + +## Usage + +<<< ./snippets/validate-my-credentials.js diff --git a/doc/6/controllers/auth/validate-my-credentials/snippets/validate-my-credentials.js b/doc/6/controllers/auth/validate-my-credentials/snippets/validate-my-credentials.js new file mode 100644 index 000000000..84a5d4b0e --- /dev/null +++ b/doc/6/controllers/auth/validate-my-credentials/snippets/validate-my-credentials.js @@ -0,0 +1,13 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const valid = await kuzzle.auth.validateMyCredentials('local', credentials); + + if (valid === true) { + console.log('Credentials are valid'); + } +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/auth/validate-my-credentials/snippets/validate-my-credentials.test.yml b/doc/6/controllers/auth/validate-my-credentials/snippets/validate-my-credentials.test.yml new file mode 100644 index 000000000..0f62e9367 --- /dev/null +++ b/doc/6/controllers/auth/validate-my-credentials/snippets/validate-my-credentials.test.yml @@ -0,0 +1,10 @@ +name: auth#validateMyCredentials +description: Validate the current user's credentials for the specified ``. +hooks: + before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: curl -X DELETE kuzzle:7512/users/foo +template: default +expected: Credentials are valid + +sdk: js +version: 6 diff --git a/doc/6/controllers/bulk/import/index.md b/doc/6/controllers/bulk/import/index.md new file mode 100644 index 000000000..6e53b196b --- /dev/null +++ b/doc/6/controllers/bulk/import/index.md @@ -0,0 +1,85 @@ +--- +code: true +type: page +title: import +description: Performs a bulk import on a collection +--- + +# Import + +Create, update or delete large amount of documents as fast as possible. + +This route is faster than the `document:m*` routes family (e.g. [document:mCreate](/sdk/js/6/controllers/document/mCreate)), but no real-time notifications will be generated, even if some of the documents in the import match subscription filters. + +If some documents actions fail, the client will receive a [PartialError](/core/1/api/essentials/errors/#partialerror) error. + +
+ +```js +import (bulkData, [options]) +``` + +
+ +| Arguments | Type | Description | +| ---------- | ------------------- | ----------------------------------------------- | +| `bulkData` | 
object[]
| List of documents to be added to the collection | +| `options` | 
object
| Query options | + +### bulkData + +This API takes a JSON array containing a list of objects working in pairs. +In each pair, the first object specifies the action to perform (the most common is `create`) and the second specifies the document itself, like in the example below: + +```js +[ + // The action object + { create: { _id: 'id', _index: 'index', _type: 'collection' } }, + // The document object + { myField: 'myValue', myOtherField: 'myOtherValue' }, + // Another action object + { create: { _id: 'another-id', _index: 'index', _type: 'collection' } }, + // Another document object + { myField: 'anotherValue', myOtherField: 'yetAnotherValue' } +]; +``` + +Note that the action object always has an attribute whose key specifies the action to take and whose value is an object specifying the location of ano object in the database (the `_index`, `_type` and `_id` tuple). Also note that, in Elasticsearch, the field `_type` correspond to `collection` in Kuzzle. + +Possible actions are `create`, `index`, `update`, `delete`. + +Learn more at [Elasticsearch Bulk API](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/docs-bulk.html) + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +--- + +## Resolves + +An object containing information about the import status for each document. + +| Property | Type | Description | +| -------- | ------------------- | --------------------------------------------------- | +| `errors` | 
boolean
| `true` if there is some errors with the import | +| `items` | 
object[]
| Array of object containing document import statuses | + +Each object has the following structure: + +```js +{ + "": { + _id: "another-id", + status: 201 + } +} +``` + +## Usage + +<<< ./snippets/import.js diff --git a/doc/6/controllers/bulk/import/snippets/import.js b/doc/6/controllers/bulk/import/snippets/import.js new file mode 100644 index 000000000..a0011e997 --- /dev/null +++ b/doc/6/controllers/bulk/import/snippets/import.js @@ -0,0 +1,40 @@ +const bulkData = [ + { create: { _id: '1', _index: 'nyc-open-data', _type: 'yellow-taxi' } }, + { a: 'document', with: 'any', number: 'of fields' }, + { create: { _id: '2', _index: 'nyc-open-data', _type: 'yellow-taxi' } }, + { another: 'document' }, + { create: { _id: '3', _index: 'nyc-open-data', _type: 'yellow-taxi' } }, + { and: { another: 'one' } } +]; + +try { + const response = await kuzzle.bulk.import(bulkData); + console.log(response); + /* + { errors: false, + items: + [ { + create: { + _id: "uniq-id-1", + status: 201 + } + }, + { + create: { + _id: "uniq-id-2", + status: 201 + } + }, + { + create: { + _id: "uniq-id-3", + status: 206 + } + } ] } + */ + const successfulImport = response.items.filter(item => item.create.status === 201); + + console.log(`Successfully imported ${successfulImport.length} documents`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/bulk/import/snippets/import.test.yml b/doc/6/controllers/bulk/import/snippets/import.test.yml new file mode 100644 index 000000000..72ef6d02f --- /dev/null +++ b/doc/6/controllers/bulk/import/snippets/import.test.yml @@ -0,0 +1,13 @@ +--- +name: bulk#import +description: Bulk imports three documents into Kuzzle +hooks: + before: | + curl -X POST kuzzle:7512/nyc-open-data/_create + curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi + after: curl -X DELETE kuzzle:7512/nyc-open-data +template: default +expected: Successfully imported 3 documents + +sdk: js +version: 6 diff --git a/doc/6/controllers/bulk/index.md b/doc/6/controllers/bulk/index.md new file mode 100644 index 000000000..33c10f9c7 --- /dev/null +++ b/doc/6/controllers/bulk/index.md @@ -0,0 +1,6 @@ +--- +code: true +type: branch +title: bulk +description: bulk controller documentation +--- diff --git a/doc/6/controllers/collection/create/index.md b/doc/6/controllers/collection/create/index.md new file mode 100644 index 000000000..ece434f22 --- /dev/null +++ b/doc/6/controllers/collection/create/index.md @@ -0,0 +1,67 @@ +--- +code: true +type: page +title: create +description: Create a new collection +--- + +# create + +Creates a new [collection](/core/1/guides/essentials/persisted/) in Kuzzle via the persistence engine, in the provided index. + +You can also provide an optional data mapping that allow you to exploit the full capabilities of our +persistent data storage layer, [ElasticSearch](https://www.elastic.co/products/elasticsearch) (check here the [mapping capabilities of ElasticSearch](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping.html)). + +This method will only update the mapping if the collection already exists. + +
+ +```js +create(index, collection, [mapping], [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `mapping` | 
object
| Describes the data mapping to associate to the new collection, using Elasticsearch [mapping format](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping.html) | +| `options` | 
object
| Query options | + +### mapping + +An object representing the data mapping of the collection. + +The mapping must have a root field `properties` that contain the mapping definition: + +```js +const mapping = { + properties: { + field1: { type: 'text' }, + field2: { + properties: { + nestedField: { type: 'keyword' } + } + } + } +}; +``` + +More informations about database mappings [here](/core/1/guides/essentials/database-mappings). + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves if the collection is successfully created. + +## Usage + +<<< ./snippets/create.js diff --git a/doc/6/controllers/collection/create/snippets/create.js b/doc/6/controllers/collection/create/snippets/create.js new file mode 100644 index 000000000..4c10502d6 --- /dev/null +++ b/doc/6/controllers/collection/create/snippets/create.js @@ -0,0 +1,19 @@ +const mapping = { + properties: { + license: { type: 'keyword' }, + driver: { + properties: { + name: { type: 'keyword' }, + curriculum: { type: 'text' } + } + } + } +}; + +try { + await kuzzle.collection.create('nyc-open-data', 'yellow-taxi', mapping); + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/create/snippets/create.test.yml b/doc/6/controllers/collection/create/snippets/create.test.yml new file mode 100644 index 000000000..15793fcf0 --- /dev/null +++ b/doc/6/controllers/collection/create/snippets/create.test.yml @@ -0,0 +1,10 @@ +name: collection#create +description: Create a new collection +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create + after: +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/delete-specifications/index.md b/doc/6/controllers/collection/delete-specifications/index.md new file mode 100644 index 000000000..3445f924b --- /dev/null +++ b/doc/6/controllers/collection/delete-specifications/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: deleteSpecifications +description: Delete validation specifications for a collection +--- + +# deleteSpecifications + +Deletes validation specifications for a collection. + +
+ +```js +deleteSpecifications(index, collection, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves if successful. + +## Usage + +<<< ./snippets/delete-specifications.js diff --git a/doc/6/controllers/collection/delete-specifications/snippets/delete-specifications.js b/doc/6/controllers/collection/delete-specifications/snippets/delete-specifications.js new file mode 100644 index 000000000..6672ffd79 --- /dev/null +++ b/doc/6/controllers/collection/delete-specifications/snippets/delete-specifications.js @@ -0,0 +1,7 @@ +try { + await kuzzle.collection.deleteSpecifications('nyc-open-data', 'yellow-taxi'); + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/delete-specifications/snippets/delete-specifications.test.yml b/doc/6/controllers/collection/delete-specifications/snippets/delete-specifications.test.yml new file mode 100644 index 000000000..5542ecfe0 --- /dev/null +++ b/doc/6/controllers/collection/delete-specifications/snippets/delete-specifications.test.yml @@ -0,0 +1,10 @@ +name: collection#deleteSpecifications +description: Delete validation specifications for a collection +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create && curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/exists/index.md b/doc/6/controllers/collection/exists/index.md new file mode 100644 index 000000000..8a8000677 --- /dev/null +++ b/doc/6/controllers/collection/exists/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: exists +description: Check if collection exists +--- + +# exists + +Check if a collection exists in Kuzzle. + +
+ +```js +exists(index, collection, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to `true` if the collection exists, `false` otherwise. + +## Usage + +<<< ./snippets/exists.js diff --git a/doc/6/controllers/collection/exists/snippets/exists.js b/doc/6/controllers/collection/exists/snippets/exists.js new file mode 100644 index 000000000..167a241af --- /dev/null +++ b/doc/6/controllers/collection/exists/snippets/exists.js @@ -0,0 +1,9 @@ +try { + const exists = kuzzle.collection.exists('nyc-open-data', 'green-taxi'); + + if (exists) { + console.log('Success'); + } +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/exists/snippets/exists.test.yml b/doc/6/controllers/collection/exists/snippets/exists.test.yml new file mode 100644 index 000000000..3c3c4e32d --- /dev/null +++ b/doc/6/controllers/collection/exists/snippets/exists.test.yml @@ -0,0 +1,10 @@ +name: collection#exists +description: Check if collection exists +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create && curl -X PUT kuzzle:7512/nyc-open-data/green-taxi + after: +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/get-mapping/index.md b/doc/6/controllers/collection/get-mapping/index.md new file mode 100644 index 000000000..0f0fdcade --- /dev/null +++ b/doc/6/controllers/collection/get-mapping/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: getMapping +description: Return collection mapping +--- + +# getMapping + +Returns the collection mapping. + +
+ +```js +getMapping(index, collection, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to an `object` representing the collection mapping. + +## Usage + +<<< ./snippets/get-mapping.js diff --git a/doc/6/controllers/collection/get-mapping/snippets/get-mapping.js b/doc/6/controllers/collection/get-mapping/snippets/get-mapping.js new file mode 100644 index 000000000..772aa3455 --- /dev/null +++ b/doc/6/controllers/collection/get-mapping/snippets/get-mapping.js @@ -0,0 +1,31 @@ +try { + const mapping = await kuzzle.collection.getMapping('nyc-open-data', 'yellow-taxi'); + console.log(mapping); + /* + { + "nyc-open-data": { + "mappings": { + "yellow-taxi": { + dynamic: 'false', + _meta: { + area: 'Panipokhari + }, + properties: { + license: { type: 'keyword' }, + driver: { + properties: { + name: { type: 'keyword' }, + curriculum: { type: 'text' } + } + } + } + } + } + } + } + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/get-mapping/snippets/get-mapping.test.yml b/doc/6/controllers/collection/get-mapping/snippets/get-mapping.test.yml new file mode 100644 index 000000000..3d0570200 --- /dev/null +++ b/doc/6/controllers/collection/get-mapping/snippets/get-mapping.test.yml @@ -0,0 +1,10 @@ +name: collection#getMapping +description: Return collection mapping +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create && curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/get-specifications/index.md b/doc/6/controllers/collection/get-specifications/index.md new file mode 100644 index 000000000..955197268 --- /dev/null +++ b/doc/6/controllers/collection/get-specifications/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: getSpecifications +description: Returns the validation specifications +--- + +# getSpecifications + +Returns the validation specifications associated to the given index and collection. + +
+ +```js +getSpecifications(index, collection, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolve to an object representing the collection specifications. + +## Usage + +<<< ./snippets/get-specifications.js diff --git a/doc/6/controllers/collection/get-specifications/snippets/get-specifications.js b/doc/6/controllers/collection/get-specifications/snippets/get-specifications.js new file mode 100644 index 000000000..14d0f14c7 --- /dev/null +++ b/doc/6/controllers/collection/get-specifications/snippets/get-specifications.js @@ -0,0 +1,23 @@ +try { + const specifications = await kuzzle.collection.getSpecifications('nyc-open-data', 'yellow-taxi'); + console.log(specifications); + /* + { + "collection": "yellow-taxi", + "index": "nyc-open-data", + "validation": { + "fields": { + "age": { + "defaultValue": 42, + "mandatory": true, + "type": "integer" + } + }, + "strict": true + } + } + */ + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/get-specifications/snippets/get-specifications.test.yml b/doc/6/controllers/collection/get-specifications/snippets/get-specifications.test.yml new file mode 100644 index 000000000..a50f49c51 --- /dev/null +++ b/doc/6/controllers/collection/get-specifications/snippets/get-specifications.test.yml @@ -0,0 +1,9 @@ +name: collection#getSpecifications +description: Returns the validation specifications +hooks: + before: "curl -X POST kuzzle:7512/nyc-open-data/_create && curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi && curl -X PUT -H \"Content-Type: application/json\" -d '{\"nyc-open-data\": {\"yellow-taxi\": {\"strict\": false,\"fields\": {\"license\": {\"type\": \"string\"}}}}}' kuzzle:7512/_specifications" + after: +template: default +expected: Success +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/index.md b/doc/6/controllers/collection/index.md new file mode 100644 index 000000000..a263a05db --- /dev/null +++ b/doc/6/controllers/collection/index.md @@ -0,0 +1,6 @@ +--- +code: true +type: branch +title: collection +description: collection controller documentation +--- diff --git a/doc/6/controllers/collection/list/index.md b/doc/6/controllers/collection/list/index.md new file mode 100644 index 000000000..c6b5f6d55 --- /dev/null +++ b/doc/6/controllers/collection/list/index.md @@ -0,0 +1,56 @@ +--- +code: true +type: page +title: list +description: Returns the collection list of an index +--- + +# list + +Returns the list of collections associated to a provided index. +The returned list is sorted in alphanumerical order. + +
+ +```js +list(index, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `index` | 
string
| Index name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `from` | 
number

(`0`) | Offset of the first result | +| `size` | 
number

(`10`) | Maximum number of returned results | + +## Resolves + +Resolves to an object containing the following properties: + +| Property | Type | Description | +| ------------- | ------------------- | ------------------------------------------------------------------ | +| `type` | 
string
| Types of returned collections
(`all`, `realtime` or `stored`) | +| `collections` | 
object[]
| List of collections | +| `from` | 
number
| Offset of the first result | +| `size` | 
number
| Maximum number of returned results | + +Each object in the `collections` array contains the following properties: + +| Property | Type | Description | +| -------- | ----------------- | ---------------------------------------- | +| `name` | 
string
| Collection name | +| `type` | 
string
| Collection type (`realtime` or `stored`) | + +## Usage + +<<< ./snippets/list.js diff --git a/doc/6/controllers/collection/list/snippets/list.js b/doc/6/controllers/collection/list/snippets/list.js new file mode 100644 index 000000000..aa6388f3c --- /dev/null +++ b/doc/6/controllers/collection/list/snippets/list.js @@ -0,0 +1,18 @@ +try { + const options = { from: 1, size: 1 }; + + const collectionList = await kuzzle.collection.list('mtp-open-data', options); + console.log(collectionList); + /* + { + type: 'all', + collections: [ { name: 'pink-taxi', type: 'stored' } ], + from: 1, + size: 1 + } + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/list/snippets/list.test.yml b/doc/6/controllers/collection/list/snippets/list.test.yml new file mode 100644 index 000000000..39641aa7b --- /dev/null +++ b/doc/6/controllers/collection/list/snippets/list.test.yml @@ -0,0 +1,10 @@ +name: collection#list +description: Returns the collection list of an index +hooks: + before: curl -X POST kuzzle:7512/mtp-open-data/_create && curl -X PUT kuzzle:7512/mtp-open-data/pink-taxi && curl -X PUT kuzzle:7512/mtp-open-data/dark-taxi + after: +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/search-specifications/index.md b/doc/6/controllers/collection/search-specifications/index.md new file mode 100644 index 000000000..89ba5727a --- /dev/null +++ b/doc/6/controllers/collection/search-specifications/index.md @@ -0,0 +1,70 @@ +--- +code: true +type: page +title: searchSpecifications +description: Search for specifications +--- + +# searchSpecifications + + + +Searches collection specifications. + +There is a limit to how many items can be returned by a single search query. +That limit is by default set at 10000, and you can't get over it even with the from and size pagination options. + +:::info +When processing a large number of items (i.e. more than 1000), it is advised to paginate the results using [SearchResult.next](/sdk/js/6/core-classes/search-result/next/) rather than increasing the size parameter. +::: + +
+ +```js +searchSpecifications([body], [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------------------- | +| `body` | 
object
| An object containing the search query | +| `options` | 
object
| Query options | + +### body + +The body is a set of filters using [Elasticsearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-body.html) to match the documents you are looking for. +The filters must be inside the `query` property of the body. + +Example: + +```js +const body = { + query: { + match_all: { + boost: 1 + } + } +}; +``` + +### options + +| Arguments | Type | Description | +| ---------- | ------------------------------- | ------------------------------------ | +| `queuable` | 
boolean

(`true`) | Make this request queuable or not | +| `from` | 
number

(`0`) | Offset of the first document | +| `size` | 
number

(`10`) | Maximum number of documents returned | +| `scroll` | 
string

| Maximum duration for scroll session | + +- `size` controls the maximum number of documents returned in the response +- `from` is usually used with the `size` argument, and defines the offset from the first result you want to fetch +- `scroll` is used to fetch large result sets, and it must be set with a [time duration](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/common-options.html#time-units). If set, a forward-only cursor will be created (and automatically destroyed at the end of the set duration), and its identifier will be returned in the `scrollId` property, along with the first page of the results. + +## Resolves + +Resolve to a [SpecificationsSearchResult](/sdk/js/6/core-classes/search-result). + +## Usage + +<<< ./snippets/search-specifications.js diff --git a/doc/6/controllers/collection/search-specifications/snippets/search-specifications.js b/doc/6/controllers/collection/search-specifications/snippets/search-specifications.js new file mode 100644 index 000000000..af3c1bb4b --- /dev/null +++ b/doc/6/controllers/collection/search-specifications/snippets/search-specifications.js @@ -0,0 +1,47 @@ +try { + const body = { + query: { + match_all: { + boost: 1 + } + } + }; + + const options = { + size: 50, + offset: 0, + scroll: '10m' + }; + + const searchResult = await kuzzle.collection.searchSpecifications(body, options); + console.log(searchResult); + /* + { + "total": 1, + "max_score": 1, + "hits": [ + { + "_index": "%kuzzle", + "_type": "validations", + "_id": "nyc-open-data#yellow-taxi", + "_score": 1, + "_source": { + "validation": { + "strict": false, + "fields": { + "license": { + "type": "string" + } + } + }, + "index": "nyc-open-data", + "collection": "yellow-taxi" + } + } + ], + "scrollId": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAACSFlgtZTJFYjNiU1FxQzhSNUFpNlZHZGcAAAAAAAAAkxZYLWUyRWIzYlNRcUM4UjVBaTZWR2RnAAAAAAAAAJQWWC1lMkViM2JTUXFDOFI1QWk2VkdkZwAAAAAAAACVFlgtZTJFYjNiU1FxQzhSNUFpNlZHZGcAAAAAAAAAlhZYLWUyRWIzYlNRcUM4UjVBaTZWR2Rn" + } + */ +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/search-specifications/snippets/search-specifications.test.yml b/doc/6/controllers/collection/search-specifications/snippets/search-specifications.test.yml new file mode 100644 index 000000000..f32b7aa16 --- /dev/null +++ b/doc/6/controllers/collection/search-specifications/snippets/search-specifications.test.yml @@ -0,0 +1,23 @@ +name: collection#searchSpecifications +description: Search for specifications +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -X POST kuzzle:7512/nyc-open-data/_create + curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi + curl -X PUT -H "Content-Type: application/json" -d '{ + "nyc-open-data": { + "yellow-taxi": { + "strict": false, + "fields": { + "license": { + "type": "string" + } + } + } + } + }' kuzzle:7512/_specifications?refresh=wait_for +template: default +expected: 'fetched: 1' +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/truncate/index.md b/doc/6/controllers/collection/truncate/index.md new file mode 100644 index 000000000..0f38bac7f --- /dev/null +++ b/doc/6/controllers/collection/truncate/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: truncate +description: Remove all documents from collection +--- + +# truncate + +Removes all documents from a collection, while keeping the associated mapping. + +
+ +```js +truncate(index, collection, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves when the collection is successfully truncated. + +## Usage + +<<< ./snippets/truncate.js diff --git a/doc/6/controllers/collection/truncate/snippets/truncate.js b/doc/6/controllers/collection/truncate/snippets/truncate.js new file mode 100644 index 000000000..84c9f8ff1 --- /dev/null +++ b/doc/6/controllers/collection/truncate/snippets/truncate.js @@ -0,0 +1,7 @@ +try { + await kuzzle.collection.truncate('nyc-open-data', 'yellow-taxi'); + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/truncate/snippets/truncate.test.yml b/doc/6/controllers/collection/truncate/snippets/truncate.test.yml new file mode 100644 index 000000000..f34edd066 --- /dev/null +++ b/doc/6/controllers/collection/truncate/snippets/truncate.test.yml @@ -0,0 +1,10 @@ +name: collection#truncate +description: Remove all documents from collection +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create && curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/update-mapping/index.md b/doc/6/controllers/collection/update-mapping/index.md new file mode 100644 index 000000000..f01043b23 --- /dev/null +++ b/doc/6/controllers/collection/update-mapping/index.md @@ -0,0 +1,66 @@ +--- +code: true +type: page +title: updateMapping +description: Update the collection mapping +--- + +# updateMapping + + + +You can define the collection [dynamic mapping policy](/core/1/guides/essentials/database-mappings/#dynamic-mapping-policy) by setting the `dynamic` field to the desired value. + +You can define [collection additional metadata](/core/1/guides/essentials/database-mappings/#collection-metadata) within the `_meta` root field. + +
+ +```js +updateMapping(index, collection, mapping, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `mapping` | 
object
| Describes the collection mapping | +| `options` | 
object
| Query options | + +### mapping + +An object representing the collection data mapping. + +This object must have a root field `properties` that contain the mapping definition: + +```js +const mapping = { + properties: { + field1: { type: 'text' }, + field2: { + properties: { + nestedField: { type: 'keyword' } + } + } + } +}; +``` + +More informations about database mappings [here](/core/1/guides/essentials/database-mappings). + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolve if the collection is successfully updated. + +## Usage + +<<< ./snippets/update-mapping.js diff --git a/doc/6/controllers/collection/update-mapping/snippets/update-mapping.js b/doc/6/controllers/collection/update-mapping/snippets/update-mapping.js new file mode 100644 index 000000000..d286a6c0a --- /dev/null +++ b/doc/6/controllers/collection/update-mapping/snippets/update-mapping.js @@ -0,0 +1,17 @@ +const mapping = { + dynamic: 'false', + _meta: { + area: 'Panipokhari' + }, + properties: { + plate: { type: 'keyword' } + } +}; + +try { + await kuzzle.collection.updateMapping('nyc-open-data', 'yellow-taxi', mapping); + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/update-mapping/snippets/update-mapping.test.yml b/doc/6/controllers/collection/update-mapping/snippets/update-mapping.test.yml new file mode 100644 index 000000000..272e5e002 --- /dev/null +++ b/doc/6/controllers/collection/update-mapping/snippets/update-mapping.test.yml @@ -0,0 +1,10 @@ +name: collection#updateMapping +description: Update the collection mapping +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create && curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/update-specifications/index.md b/doc/6/controllers/collection/update-specifications/index.md new file mode 100644 index 000000000..229434640 --- /dev/null +++ b/doc/6/controllers/collection/update-specifications/index.md @@ -0,0 +1,58 @@ +--- +code: true +type: page +title: updateSpecifications +description: Update the validation specifications +--- + +# updateSpecifications + +The updateSpecifications method allows you to create or update the validation specifications for a collection. + +When the validation specification is not formatted correctly, a detailed error message is returned to help you to debug. + +
+ +```js +updateSpecifications(index, collection, specifications, [options]); +``` + +
+ +| Arguments | Type | Description | +| ---------------- | ----------------- | ------------------------ | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `specifications` | 
object
| Specifications to update | +| `options` | 
object
| Query options | + +### specifications + +An object representing the specifications. + +This object must follow the [Specification Structure](/core/1/guides/essentials/data-validation/): + +```js +{ + strict: , + fields: { + // ... specification for each field + } +} +``` + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolve to an object containing the specifications. + +## Usage + +<<< ./snippets/update-specifications.js diff --git a/doc/6/controllers/collection/update-specifications/snippets/update-specifications.js b/doc/6/controllers/collection/update-specifications/snippets/update-specifications.js new file mode 100644 index 000000000..af495e99a --- /dev/null +++ b/doc/6/controllers/collection/update-specifications/snippets/update-specifications.js @@ -0,0 +1,25 @@ +const specifications = { + strict: false, + fields: { + license: { + mandatory: true, + type: 'string' + } + } +}; + +try { + const result = await kuzzle.collection.updateSpecifications('nyc-open-data', 'yellow-taxi', specifications); + console.log(result); + /* + { strict: false, + fields: { + license: { + mandatory: true, + type: 'string' } } } + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/update-specifications/snippets/update-specifications.test.yml b/doc/6/controllers/collection/update-specifications/snippets/update-specifications.test.yml new file mode 100644 index 000000000..9a9ef7582 --- /dev/null +++ b/doc/6/controllers/collection/update-specifications/snippets/update-specifications.test.yml @@ -0,0 +1,10 @@ +name: collection#updateSpecifications +description: Update the validation specifications +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create && curl -X PUT kuzzle:7512/nyc-open-data/green-taxi + after: curl -X DELETE kuzzle:7512/nyc-open-data/yellow-taxi/_specifications +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/collection/validate-specifications/index.md b/doc/6/controllers/collection/validate-specifications/index.md new file mode 100644 index 000000000..23d96e712 --- /dev/null +++ b/doc/6/controllers/collection/validate-specifications/index.md @@ -0,0 +1,66 @@ +--- +code: true +type: page +title: validateSpecifications +description: Validate specifications format +--- + +# validateSpecifications + +The validateSpecifications method checks if a validation specification is well formatted. It does not store or modify the existing specification. + +When the validation specification is not formatted correctly, a detailed error message is returned to help you to debug. + +
+ +```js +validateSpecifications(index, collection, specifications, [options]); +``` + +
+ +| Arguments | Type | Description | +| ---------------- | ----------------- | -------------------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `specifications` | 
object
| Specifications to validate | +| `options` | 
object
| Query options | + +### specifications + +An object representing the specifications. + +This object must follow the [Specification Structure](/core/1/guides/cookbooks/datavalidation): + +```js +{ + strict: , + fields: { + // ... specification for each field + } +} +``` + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to an object which contain information about the specifications validity. + +It contains the following properties: + +| Property | Type | Description | +| ------------- | ------------------- | ---------------------------- | +| `valid` | 
boolean
| Specifications validity | +| `details` | 
string[]
| Specifications errors | +| `description` | 
string
| Global description of errors | + +## Usage + +<<< ./snippets/validate-specifications.js diff --git a/doc/6/controllers/collection/validate-specifications/snippets/validate-specifications.js b/doc/6/controllers/collection/validate-specifications/snippets/validate-specifications.js new file mode 100644 index 000000000..772108c04 --- /dev/null +++ b/doc/6/controllers/collection/validate-specifications/snippets/validate-specifications.js @@ -0,0 +1,29 @@ +try { + const specifications = { + strict: false, + fields: { + license: { + mandatory: true, + type: 'symbol' // symbol is not a recognized type + } + } + }; + + const result = await kuzzle.collection.validateSpecifications('nyc-open-data', 'yellow-taxi', specifications); + console.log(result); + /* + { + valid: false, + details: [ + 'In nyc-open-data.yellow-taxi.license: symbol is not a recognized type.' + ], + description: 'Some errors with provided specifications.' + } + */ + + if (result.valid === false) { + console.log(result.description); + } +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/collection/validate-specifications/snippets/validate-specifications.test.yml b/doc/6/controllers/collection/validate-specifications/snippets/validate-specifications.test.yml new file mode 100644 index 000000000..9f7b8a750 --- /dev/null +++ b/doc/6/controllers/collection/validate-specifications/snippets/validate-specifications.test.yml @@ -0,0 +1,10 @@ +name: collection#validateSpecifications +description: Validate specifications format +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create && curl -X PUT kuzzle:7512/nyc-open-data/green-taxi + after: +template: default +expected: Some errors with provided specifications. + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/count/index.md b/doc/6/controllers/document/count/index.md new file mode 100644 index 000000000..9b4bb5660 --- /dev/null +++ b/doc/6/controllers/document/count/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: count +description: Count documents matching the given query +--- + +# count + +Counts documents in a collection. + +A query can be provided to alter the count result, otherwise returns the total number of documents in the collection. + +Kuzzle uses the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl.html) syntax. + +
+ +```js +count(index, collection, query, [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `query` | 
object
| Query to match | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to the number of matched documents. + +## Usage + +<<< ./snippets/count.js diff --git a/doc/6/controllers/document/count/snippets/count.js b/doc/6/controllers/document/count/snippets/count.js new file mode 100644 index 000000000..ae59873a8 --- /dev/null +++ b/doc/6/controllers/document/count/snippets/count.js @@ -0,0 +1,15 @@ +try { + const count = await kuzzle.document.count( + 'nyc-open-data', + 'yellow-taxi', + { + query: { + match: { license: 'valid' } + } + } + ); + + console.log(`Found ${count} documents matching license:valid`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/count/snippets/count.test.yml b/doc/6/controllers/document/count/snippets/count.test.yml new file mode 100644 index 000000000..0ff409fe9 --- /dev/null +++ b/doc/6/controllers/document/count/snippets/count.test.yml @@ -0,0 +1,22 @@ +--- +name: document#count +description: Count documents matching the given query +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + for i in 1 2 3 4 5; do + curl -H "Content-type: application/json" -d '{"license": "valid"}' kuzzle:7512/nyc-open-data/yellow-taxi/_create + done + for i in 1 2 3 4 5; do + curl -H "Content-type: application/json" -d '{}' kuzzle:7512/nyc-open-data/yellow-taxi/_create + done + curl -XPOST kuzzle:7512/nyc-open-data/_refresh + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Found 5 documents matching license:valid + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/create/index.md b/doc/6/controllers/document/create/index.md new file mode 100644 index 000000000..8515405eb --- /dev/null +++ b/doc/6/controllers/document/create/index.md @@ -0,0 +1,51 @@ +--- +code: true +type: page +title: create +description: Create a new document +--- + +# create + +Creates a new document in the persistent data storage. + +Throws an error if the document already exists. + +The optional parameter `refresh` can be used with the value `wait_for` in order to wait for the document to be indexed (indexed documents are available for `search`). + +
+ +```js +create(index, collection, document, [id], [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | -------------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `document` | 
object
| Document content | +| `id` | 
string
| Optional document ID | +| `options` | 
object
| Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | 
string

(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | + +## Resolves + +Resolves to an object containing the document creation result. + +| Name | Type | Description | +| --------- | ----------------- | ------------------------------------------------------ | +| \_id | 
string
| ID of the newly created document | +| \_version | 
number
| Version of the document in the persistent data storage | +| \_source | 
object
| Created document | + +## Usage + +<<< ./snippets/create.js diff --git a/doc/6/controllers/document/create/snippets/create.js b/doc/6/controllers/document/create/snippets/create.js new file mode 100644 index 000000000..b9dccf166 --- /dev/null +++ b/doc/6/controllers/document/create/snippets/create.js @@ -0,0 +1,33 @@ +try { + const response = await kuzzle.document.create( + 'nyc-open-data', + 'yellow-taxi', + { lastName: 'Eggins' }, + 'some-id' + ); + + if (response._id === 'some-id') { + console.log('Success'); + } + /* + response = + { _index: 'nyc-open-data', + _type: 'yellow-taxi', + _id: 'some-id', + _version: 1, + result: 'created', + _shards: { total: 2, successful: 1, failed: 0 }, + created: true, + _source: + { lastName: 'Eggins', + _kuzzle_info: + { author: '-1', + createdAt: 1537443212089, + updatedAt: null, + updater: null, + active: true, + deletedAt: null } } } + */ +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/create/snippets/create.test.yml b/doc/6/controllers/document/create/snippets/create.test.yml new file mode 100644 index 000000000..a70c73244 --- /dev/null +++ b/doc/6/controllers/document/create/snippets/create.test.yml @@ -0,0 +1,14 @@ +name: document#create +description: Create a new document +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/createOrReplace/index.md b/doc/6/controllers/document/createOrReplace/index.md new file mode 100644 index 000000000..1851b8ed4 --- /dev/null +++ b/doc/6/controllers/document/createOrReplace/index.md @@ -0,0 +1,49 @@ +--- +code: true +type: page +title: createOrReplace +description: Creates or replaces a document +--- + +# createOrReplace + +Creates a new document in the persistent data storage, or replaces its content if it already exists. + +The optional parameter `refresh` can be used with the value `wait_for` in order to wait for the document to be indexed (indexed documents are available for `search`). + +
+ +```js +createOrReplace(index, collection, id, document, [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | ---------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `id` | 
string
| Document ID | +| `document` | 
object
| Document content | +| `options` | 
object
| Query options | + +### **Options** + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | 
string

(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | + +## Resolves + +Resolves to an object containing the document creation result. + +| Name | Type | Description | +| --------- | ----------------- | ---------------------------------------------------------- | +| \_id | 
string
| The id of the newly created document | +| \_version | 
number
| The version of the document in the persistent data storage | +| \_source | 
object
| The created document | + +## Usage + +<<< ./snippets/create-or-replace.js diff --git a/doc/6/controllers/document/createOrReplace/snippets/create-or-replace.js b/doc/6/controllers/document/createOrReplace/snippets/create-or-replace.js new file mode 100644 index 000000000..0aeac5744 --- /dev/null +++ b/doc/6/controllers/document/createOrReplace/snippets/create-or-replace.js @@ -0,0 +1,33 @@ +try { + const response = await kuzzle.document.createOrReplace( + 'nyc-open-data', + 'yellow-taxi', + 'some-id', + { lastName: 'McHan' } + ); + + if (response._id === 'some-id') { + console.log('Success'); + } + /* + response = + { _index: 'nyc-open-data', + _type: 'yellow-taxi', + _id: 'some-id', + _version: 1, + result: 'created', + _shards: { total: 2, successful: 1, failed: 0 }, + created: true, + _source: + { lastName: 'McHan', + _kuzzle_info: + { author: '-1', + createdAt: 1537443212089, + updatedAt: null, + updater: null, + active: true, + deletedAt: null } } } + */ +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/createOrReplace/snippets/create-or-replace.test.yml b/doc/6/controllers/document/createOrReplace/snippets/create-or-replace.test.yml new file mode 100644 index 000000000..a6302a57c --- /dev/null +++ b/doc/6/controllers/document/createOrReplace/snippets/create-or-replace.test.yml @@ -0,0 +1,14 @@ +name: document#createOrReplace +description: Creates or replaces a document +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/delete/index.md b/doc/6/controllers/document/delete/index.md new file mode 100644 index 000000000..f93577750 --- /dev/null +++ b/doc/6/controllers/document/delete/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: delete +description: Deletes a document from kuzzle +--- + +# delete + +Deletes a document. + +The optional parameter `refresh` can be used with the value `wait_for` in order to wait for the document to be indexed (and to no longer be available in search). + +
+ +```js +delete (index, collection, id, [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `id` | 
string
| Document ID | +| `options` | 
object
| Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | 
string

(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | + +## Resolves + +Resolves to the id of the deleted document. + +## Usage + +<<< ./snippets/delete.js diff --git a/doc/6/controllers/document/delete/snippets/delete.js b/doc/6/controllers/document/delete/snippets/delete.js new file mode 100644 index 000000000..a1700237a --- /dev/null +++ b/doc/6/controllers/document/delete/snippets/delete.js @@ -0,0 +1,9 @@ +try { + const id = await kuzzle.document.delete('nyc-open-data', 'yellow-taxi', 'some-id'); + + if (id === 'some-id') { + console.log('Success'); + } +} catch (error) { + console.error(error.message); +} \ No newline at end of file diff --git a/doc/6/controllers/document/delete/snippets/delete.test.yml b/doc/6/controllers/document/delete/snippets/delete.test.yml new file mode 100644 index 000000000..3b885c736 --- /dev/null +++ b/doc/6/controllers/document/delete/snippets/delete.test.yml @@ -0,0 +1,15 @@ +name: document#delete +description: Deletes a document from kuzzle +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + curl -H "Content-type: application/json" -XPUT -d '{}' kuzzle:7512/nyc-open-data/yellow-taxi/some-id + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/deleteByQuery/index.md b/doc/6/controllers/document/deleteByQuery/index.md new file mode 100644 index 000000000..2cec180a0 --- /dev/null +++ b/doc/6/controllers/document/deleteByQuery/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: deleteByQuery +description: Delete documents matching query +--- + +# deleteByQuery + +Deletes documents matching the provided search query. + +Kuzzle uses the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl.html) syntax. + +An empty or null query will match all documents in the collection. + +
+ +```js +deleteByQuery(index, collection, [query], [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `query` | 
object
| Query to match | +| `options` | 
object
| Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | 
string

(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | + +## Resolves + +Resolves to an array of strings containing the deleted document ids. + +## Usage + +<<< ./snippets/delete-by-query.js diff --git a/doc/6/controllers/document/deleteByQuery/snippets/delete-by-query.js b/doc/6/controllers/document/deleteByQuery/snippets/delete-by-query.js new file mode 100644 index 000000000..ad36861b6 --- /dev/null +++ b/doc/6/controllers/document/deleteByQuery/snippets/delete-by-query.js @@ -0,0 +1,15 @@ +try { + const deleted = await kuzzle.document.deleteByQuery( + 'nyc-open-data', + 'yellow-taxi', + { + query: { + term: { capacity: 7 } + } + } + ); + + console.log(`Successfully deleted ${deleted.length} documents`); +} catch (error) { + console.error(error.message); +} \ No newline at end of file diff --git a/doc/6/controllers/document/deleteByQuery/snippets/delete-by-query.test.yml b/doc/6/controllers/document/deleteByQuery/snippets/delete-by-query.test.yml new file mode 100644 index 000000000..f7889d668 --- /dev/null +++ b/doc/6/controllers/document/deleteByQuery/snippets/delete-by-query.test.yml @@ -0,0 +1,24 @@ +name: document#deleteByQuery +description: Delete documents matching query +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + + for i in 1 2 3 4 5; do + curl -H "Content-type: application/json" -d '{"capacity": 4}' kuzzle:7512/nyc-open-data/yellow-taxi/_create + done + + for i in 1 2 3 4 5; do + curl -H "Content-type: application/json" -d '{"capacity": 7}' kuzzle:7512/nyc-open-data/yellow-taxi/_create + done + + curl -XPOST kuzzle:7512/nyc-open-data/_refresh + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Successfully deleted 5 documents + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/get/index.md b/doc/6/controllers/document/get/index.md new file mode 100644 index 000000000..2f58324f2 --- /dev/null +++ b/doc/6/controllers/document/get/index.md @@ -0,0 +1,37 @@ +--- +code: true +type: page +title: get +description: Get a document from kuzzle +--- + +# get + +Gets a document. + +
+ +```js +get(index, collection, id, [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `id` | 
string
| Document ID | +| `options` | 
object
| Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +## Usage + +<<< ./snippets/get.js diff --git a/doc/6/controllers/document/get/snippets/get.js b/doc/6/controllers/document/get/snippets/get.js new file mode 100644 index 000000000..e5e33c88e --- /dev/null +++ b/doc/6/controllers/document/get/snippets/get.js @@ -0,0 +1,30 @@ +try { + await kuzzle.document.create( + 'nyc-open-data', + 'yellow-taxi', + { capacity: 4 }, + 'some-id' + ); + + const response = await kuzzle.document.get('nyc-open-data', 'yellow-taxi', 'some-id'); + /* + { _index: 'nyc-open-data', + _type: 'yellow-taxi', + _id: 'some-id', + _version: 1, + found: true, + _source: + { capacity: 4, + _kuzzle_info: + { author: '-1', + createdAt: 1538409095673, + updatedAt: null, + updater: null, + active: true, + deletedAt: null } } } + */ + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/get/snippets/get.test.yml b/doc/6/controllers/document/get/snippets/get.test.yml new file mode 100644 index 000000000..8ba2e38a2 --- /dev/null +++ b/doc/6/controllers/document/get/snippets/get.test.yml @@ -0,0 +1,14 @@ +name: document#get +description: Get a document from kuzzle +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/index.md b/doc/6/controllers/document/index.md new file mode 100644 index 000000000..e06e625ab --- /dev/null +++ b/doc/6/controllers/document/index.md @@ -0,0 +1,8 @@ +--- +code: true +type: branch +title: document +description: Document controller +--- + +# Document Controller diff --git a/doc/6/controllers/document/mCreate/index.md b/doc/6/controllers/document/mCreate/index.md new file mode 100644 index 000000000..c6ab42416 --- /dev/null +++ b/doc/6/controllers/document/mCreate/index.md @@ -0,0 +1,47 @@ +--- +code: true +type: page +title: mCreate +description: Create multiple documents in kuzzle +--- + +# mCreate + +Creates multiple documents. + +Throws a partial error (error code 206) if one or more documents creations fail. + +
+ +```js +mCreate(index, collection, documents, [options]); +``` + +| Argument | Type | Description | +| ------------ | --------------- | ---------------------------- | +| `index` | `string` | Index name | +| `collection` | `string` | Collection name | +| `documents` | `array` | Array of documents to create | +| `options` | `object` | Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ---------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | `boolean`
(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | `string`
(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | + +## Resolves + +Resolves to an object containing created documents. + +| Property | Type | Description | +| -------- | --------------- | --------------------------------- | +| `hits` | `array` | Created documents | +| `total` | `number` | Total number of created documents | + +## Usage + +<<< ./snippets/m-create.js diff --git a/doc/6/controllers/document/mCreate/snippets/m-create.js b/doc/6/controllers/document/mCreate/snippets/m-create.js new file mode 100644 index 000000000..d3446a457 --- /dev/null +++ b/doc/6/controllers/document/mCreate/snippets/m-create.js @@ -0,0 +1,78 @@ +try { + const documents = [ + { + _id: 'some-id', + body: { 'capacity': 4 } + }, + { + body: { this: 'document id is auto-computed' } + } + ]; + const response = await kuzzle.document.mCreate( + 'nyc-open-data', + 'yellow-taxi', + documents + ); + + console.log(response); + /* + { + "hits": [ + { + "_id": "some-id", + "_source": { + "_kuzzle_info": { + "active": true, + "author": "-1", + "updater": null, + "updatedAt": null, + "deletedAt": null, + "createdAt": 1542036563677 + }, + "capacity": 4 + }, + "_index": "nyc-open-data", + "_type": "yellow-taxi", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + }, + "created": true, + "status": 201 + }, + { + "_id": "AWcIiqbeBiYFF8kkRLKg", + "_source": { + "_kuzzle_info": { + "active": true, + "author": "-1", + "updater": null, + "updatedAt": null, + "deletedAt": null, + "createdAt": 1542036563677 + }, + "this": "document id is auto-computed" + }, + "_index": "nyc-open-data", + "_type": "yellow-taxi", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + }, + "created": true, + "status": 201 + } + ], + "total": 2 + } + */ + console.log(`Successfully created ${response.total} documents`); +} catch (error) { + console.error(error.message); +} \ No newline at end of file diff --git a/doc/6/controllers/document/mCreate/snippets/m-create.test.yml b/doc/6/controllers/document/mCreate/snippets/m-create.test.yml new file mode 100644 index 000000000..f1007f6bf --- /dev/null +++ b/doc/6/controllers/document/mCreate/snippets/m-create.test.yml @@ -0,0 +1,14 @@ +name: document#mCreate +description: Create multiple documents in kuzzle +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Successfully created 2 documents + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/mCreateOrReplace/index.md b/doc/6/controllers/document/mCreateOrReplace/index.md new file mode 100644 index 000000000..a4b757831 --- /dev/null +++ b/doc/6/controllers/document/mCreateOrReplace/index.md @@ -0,0 +1,47 @@ +--- +code: true +type: page +title: mCreateOrReplace +description: Create or replace documents +--- + +# mCreateOrReplace + +Creates or replaces multiple documents. + +Throws a partial error (error code 206) if one or more document creations/replacements fail. + +
+ +```js +mCreateOrReplace(index, collection, documents, [options]); +``` + +| Argument | Type | Description | +| ------------ | --------------- | ---------------------------- | +| `index` | `string` | Index name | +| `collection` | `string` | Collection name | +| `documents` | `array` | Array of documents to create | +| `options` | `object` | Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ---------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | `boolean`
(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | `string`
(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | + +## Resolves + +Resolves to an object containing created documents. + +| Property | Type | Description | +| -------- | --------------- | --------------------------------- | +| `hits` | `array` | Created documents | +| `total` | `number` | Total number of created documents | + +## Usage + +<<< ./snippets/m-create-or-replace.js diff --git a/doc/6/controllers/document/mCreateOrReplace/snippets/m-create-or-replace.js b/doc/6/controllers/document/mCreateOrReplace/snippets/m-create-or-replace.js new file mode 100644 index 000000000..5bc7e3011 --- /dev/null +++ b/doc/6/controllers/document/mCreateOrReplace/snippets/m-create-or-replace.js @@ -0,0 +1,80 @@ +try { + const documents = [ + { + _id: 'some-id', + body: { 'capacity': 4 } + }, + { + _id: 'some-other-id', + body: { 'capacity': 4 } + } + ]; + + const response = await kuzzle.document.mCreateOrReplace( + 'nyc-open-data', + 'yellow-taxi', + documents + ); + + console.log(JSON.stringify(response)); + /* + { + "hits": [ + { + "_id": "some-id", + "_source": { + "_kuzzle_info": { + "active": true, + "author": "-1", + "updater": null, + "updatedAt": null, + "deletedAt": null, + "createdAt": 1542036740596 + }, + "capacity": 4 + }, + "_index": "nyc-open-data", + "_type": "yellow-taxi", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + }, + "created": true, + "status": 201 + }, + { + "_id": "some-other-id", + "_source": { + "_kuzzle_info": { + "active": true, + "author": "-1", + "updater": null, + "updatedAt": null, + "deletedAt": null, + "createdAt": 1542036740596 + }, + "capacity": 4 + }, + "_index": "nyc-open-data", + "_type": "yellow-taxi", + "_version": 1, + "result": "created", + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + }, + "created": true, + "status": 201 + } + ], + "total": 2 + } + */ + console.log(`Successfully createOrReplace ${response.total} documents`); +} catch (error) { + console.error(error.message); +} \ No newline at end of file diff --git a/doc/6/controllers/document/mCreateOrReplace/snippets/m-create-or-replace.test.yml b/doc/6/controllers/document/mCreateOrReplace/snippets/m-create-or-replace.test.yml new file mode 100644 index 000000000..c12b79ed6 --- /dev/null +++ b/doc/6/controllers/document/mCreateOrReplace/snippets/m-create-or-replace.test.yml @@ -0,0 +1,14 @@ +name: document#mCreateOrReplace +description: Create or replace documents +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Successfully createOrReplace 2 documents + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/mDelete/index.md b/doc/6/controllers/document/mDelete/index.md new file mode 100644 index 000000000..8f15386ed --- /dev/null +++ b/doc/6/controllers/document/mDelete/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: mDelete +description: Delete documents +--- + +# mDelete + +Deletes multiple documents. + +Throws a partial error (error code 206) if one or more document deletions fail. + +The optional parameter `refresh` can be used with the value `wait_for` in order to wait for the document indexation (indexed documents are available for `search`). + +
+ +```js +mDelete(index, collection, ids, [options]); +``` + +| Argument | Type | Description | +| ------------ | --------------- | ------------------------------ | +| `index` | `string` | Index name | +| `collection` | `string` | Collection name | +| `ids` | `array` | IDs of the documents to delete | +| `options` | `object` | Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ---------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | `boolean`
(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | `string`
(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | + +## Resolves + +Resolves to an array of objects representing the deleted documents. + +## Usage + +<<< ./snippets/m-delete.js diff --git a/doc/6/controllers/document/mDelete/snippets/m-delete.js b/doc/6/controllers/document/mDelete/snippets/m-delete.js new file mode 100644 index 000000000..5a865a222 --- /dev/null +++ b/doc/6/controllers/document/mDelete/snippets/m-delete.js @@ -0,0 +1,14 @@ +try { + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', {}, 'some-id'); + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', {}, 'some-other-id'); + + const deleted = await kuzzle.document.mDelete( + 'nyc-open-data', + 'yellow-taxi', + ['some-id', 'some-other-id'] + ); + + console.log(`Successfully deleted ${deleted.length} documents`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/mDelete/snippets/m-delete.test.yml b/doc/6/controllers/document/mDelete/snippets/m-delete.test.yml new file mode 100644 index 000000000..70ef6ef2d --- /dev/null +++ b/doc/6/controllers/document/mDelete/snippets/m-delete.test.yml @@ -0,0 +1,14 @@ +name: document#mDelete +description: Delete documents +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Successfully deleted 2 documents + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/mGet/index.md b/doc/6/controllers/document/mGet/index.md new file mode 100644 index 000000000..95c9009f2 --- /dev/null +++ b/doc/6/controllers/document/mGet/index.md @@ -0,0 +1,46 @@ +--- +code: true +type: page +title: mGet +description: Get multiple documents +--- + +# mGet + +Gets multiple documents. + +Throws a partial error (error code 206) if one or more document can not be retrieved. + +
+ +```js +mGet(index, collection, ids, [options]); +``` + +| Argument | Type | Description | +| ------------ | --------------- | --------------- | +| `index` | `string` | Index name | +| `collection` | `string` | Collection name | +| `ids` | `array` | Document ids | +| `options` | `object` | Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ---------------------- | ---------------------------------------------------------------------------- | +| `queuable` | `boolean`
(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to an object containing the retrieved documents. + +| Property | Type | Description | +| -------- | --------------- | ------------------------- | +| `hits` | `array` | Retrieved documents | +| `total` | `number` | Total retrieved documents | + +## Usage + +<<< ./snippets/m-get.js diff --git a/doc/6/controllers/document/mGet/snippets/m-get.js b/doc/6/controllers/document/mGet/snippets/m-get.js new file mode 100644 index 000000000..bca631dac --- /dev/null +++ b/doc/6/controllers/document/mGet/snippets/m-get.js @@ -0,0 +1,61 @@ +const doc1 = { capacity: 4 }; +const doc2 = { capacity: 7 }; + +try { + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', doc1, 'some-id'); + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', doc2, 'some-other-id'); + + const response = await kuzzle.document.mGet( + 'nyc-open-data', + 'yellow-taxi', + ['some-id', 'some-other-id'] + ); + + console.log(response); + /* + { + "hits": [ + { + "_index": "nyc-open-data", + "_type": "yellow-taxi", + "_id": "some-id", + "_version": 1, + "found": true, + "_source": { + "capacity": 4, + "_kuzzle_info": { + "author": "-1", + "createdAt": 1542036871353, + "updatedAt": null, + "updater": null, + "active": true, + "deletedAt": null + } + } + }, + { + "_index": "nyc-open-data", + "_type": "yellow-taxi", + "_id": "some-other-id", + "_version": 1, + "found": true, + "_source": { + "capacity": 7, + "_kuzzle_info": { + "author": "-1", + "createdAt": 1542036871374, + "updatedAt": null, + "updater": null, + "active": true, + "deletedAt": null + } + } + } + ], + "total": 2 + } + */ + console.log(`Successfully get ${response.total} documents`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/mGet/snippets/m-get.test.yml b/doc/6/controllers/document/mGet/snippets/m-get.test.yml new file mode 100644 index 000000000..d5222f8aa --- /dev/null +++ b/doc/6/controllers/document/mGet/snippets/m-get.test.yml @@ -0,0 +1,14 @@ +name: document#mGet +description: Get multiple documents +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Successfully get 2 documents + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/mReplace/index.md b/doc/6/controllers/document/mReplace/index.md new file mode 100644 index 000000000..c05a6c58c --- /dev/null +++ b/doc/6/controllers/document/mReplace/index.md @@ -0,0 +1,47 @@ +--- +code: true +type: page +title: mReplace +description: Replace documents +--- + +# mReplace + +Replaces multiple documents. + +Throws a partial error (error code 206) if one or more documents can not be replaced. + +
+ +```js +mReplace(index, collection, documents, [options]); +``` + +| Argument | Type | Description | +| ------------ | --------------- | ---------------------------- | +| `index` | `string` | Index name | +| `collection` | `string` | Collection name | +| `documents` | `array` | Array of documents to update | +| `options` | `object` | Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ---------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | `boolean`
(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | `string`
(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | + +## Resolves + +Resolves to an object containing the replaced documents. + +| Property | Type | Description | +| -------- | --------------- | ------------------------ | +| `hits` | `array` | Replaced documents | +| `total` | `number` | Total replaced documents | + +## Usage + +<<< ./snippets/m-replace.js diff --git a/doc/6/controllers/document/mReplace/snippets/m-replace.js b/doc/6/controllers/document/mReplace/snippets/m-replace.js new file mode 100644 index 000000000..52a1821e3 --- /dev/null +++ b/doc/6/controllers/document/mReplace/snippets/m-replace.js @@ -0,0 +1,64 @@ +try { + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', {}, 'some-id'); + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', {}, 'some-other-id'); + + const documents = [ + { + _id: 'some-id', + body: { capacity: 4 } + }, + { + _id: 'some-other-id', + body: { capacity: 4 } + } + ]; + + const response = await kuzzle.document.mReplace( + 'nyc-open-data', + 'yellow-taxi', + documents + ); + + console.log(response); + /* + { hits: + [ { _id: 'some-id', + _source: + { _kuzzle_info: + { active: true, + author: '-1', + updater: null, + updatedAt: null, + deletedAt: null, + createdAt: 1538639586995 }, + capacity: 4 }, + _index: 'nyc-open-data', + _type: 'yellow-taxi', + _version: 2, + result: 'updated', + _shards: { total: 2, successful: 1, failed: 0 }, + created: false, + status: 200 }, + { _id: 'some-other-id', + _source: + { _kuzzle_info: + { active: true, + author: '-1', + updater: null, + updatedAt: null, + deletedAt: null, + createdAt: 1538639586995 }, + capacity: 4 }, + _index: 'nyc-open-data', + _type: 'yellow-taxi', + _version: 2, + result: 'updated', + _shards: { total: 2, successful: 1, failed: 0 }, + created: false, + status: 200 } ], + total: 2 } + */ + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/mReplace/snippets/m-replace.test.yml b/doc/6/controllers/document/mReplace/snippets/m-replace.test.yml new file mode 100644 index 000000000..fe7320540 --- /dev/null +++ b/doc/6/controllers/document/mReplace/snippets/m-replace.test.yml @@ -0,0 +1,14 @@ +name: document#mReplace +description: Replace documents +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/mUpdate/index.md b/doc/6/controllers/document/mUpdate/index.md new file mode 100644 index 000000000..28dd2ec8e --- /dev/null +++ b/doc/6/controllers/document/mUpdate/index.md @@ -0,0 +1,52 @@ +--- +code: true +type: page +title: mUpdate +description: Update documents +--- + +# mUpdate + +Updates multiple documents. + +Returns a partial error (error code 206) if one or more documents can not be updated. + +Conflicts may occur if the same document gets updated multiple times within a short timespan in a database cluster. + +You can set the `retryOnConflict` optional argument (with a retry count), to tell Kuzzle to retry the failing updates the specified amount of times before rejecting the request with an error. + +
+ +```js +mUpdate(index, collection, documents, [options]); +``` + +| Argument | Type | Description | +| ------------ | --------------- | ---------------------------- | +| `index` | `string` | Index name | +| `collection` | `string` | Collection name | +| `documents` | `array` | Array of documents to update | +| `options` | `object` | Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ----------------- | ---------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | `boolean`
(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | `string`
(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | +| `retryOnConflict` | `int`
(`0`) | The number of times the database layer should retry in case of version conflict | + +## Resolves + +Resolves to an object containing the updated documents. + +| Property | Type | Description | +| -------- | --------------- | ----------------------- | +| `hits` | `array` | Updated documents | +| `total` | `number` | Total updated documents | + +## Usage + +<<< ./snippets/m-update.js diff --git a/doc/6/controllers/document/mUpdate/snippets/m-update.js b/doc/6/controllers/document/mUpdate/snippets/m-update.js new file mode 100644 index 000000000..10a7910b9 --- /dev/null +++ b/doc/6/controllers/document/mUpdate/snippets/m-update.js @@ -0,0 +1,51 @@ +const doc1 = { capacity: 4 }; +const doc2 = { capacity: 7 }; + +try { + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', doc1, 'some-id'); + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', doc2, 'some-other-id'); + + const documents = [ + { + _id: 'some-id', + body: { category: 'sedan' } + }, + { + _id: 'some-other-id', + body: { category: 'limousine' } + } + ]; + + const response = await kuzzle.document.mReplace( + 'nyc-open-data', + 'yellow-taxi', + documents + ); + + console.log(response); + /* + { hits: + [ { _id: 'some-id', + _source: { _kuzzle_info: [Object], category: 'sedan' }, + _index: 'nyc-open-data', + _type: 'yellow-taxi', + _version: 2, + result: 'updated', + _shards: { total: 2, successful: 1, failed: 0 }, + created: false, + status: 200 }, + { _id: 'some-other-id', + _source: { _kuzzle_info: [Object], category: 'limousine' }, + _index: 'nyc-open-data', + _type: 'yellow-taxi', + _version: 2, + result: 'updated', + _shards: { total: 2, successful: 1, failed: 0 }, + created: false, + status: 200 } ], + total: 2 } + */ + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/mUpdate/snippets/m-update.test.yml b/doc/6/controllers/document/mUpdate/snippets/m-update.test.yml new file mode 100644 index 000000000..58ade7ff0 --- /dev/null +++ b/doc/6/controllers/document/mUpdate/snippets/m-update.test.yml @@ -0,0 +1,14 @@ +name: document#mUpdate +description: Update documents +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/replace/index.md b/doc/6/controllers/document/replace/index.md new file mode 100644 index 000000000..f219be349 --- /dev/null +++ b/doc/6/controllers/document/replace/index.md @@ -0,0 +1,47 @@ +--- +code: true +type: page +title: replace +description: Replace a document +--- + +# replace + +Replaces the content of an existing document. + +
+ +```js +replace(index, collection, id, document, [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | ------------------------------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `id` | 
string
| Document ID | +| `document` | 
object
| New content of the document to update | +| `options` | 
object
| Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | 
string

(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | + +## Resolves + +Resolves to an object containing the the document update result. + +| Name | Type | Description | +| --------- | ----------------- | ------------------------------------------------------ | +| \_id | 
string
| ID of the newly created document | +| \_version | 
number
| Version of the document in the persistent data storage | +| \_source | 
object
| The updated document | + +## Usage + +<<< ./snippets/replace.js diff --git a/doc/6/controllers/document/replace/snippets/replace.js b/doc/6/controllers/document/replace/snippets/replace.js new file mode 100644 index 000000000..be26e5ed2 --- /dev/null +++ b/doc/6/controllers/document/replace/snippets/replace.js @@ -0,0 +1,36 @@ +const doc = { color: 'yellow' }; + +try { + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', doc, 'some-id'); + + const response = await kuzzle.document.replace( + 'nyc-open-data', + 'yellow-taxi', + 'some-id', + { capacity: 4, category: 'sedan' } + ); + + console.log(response); + /* + { _index: 'nyc-open-data', + _type: 'yellow-taxi', + _id: 'some-id', + _version: 2, + result: 'updated', + _shards: { total: 2, successful: 1, failed: 0 }, + created: false, + _source: + { capacity: 4, + category: 'sedan', + _kuzzle_info: + { author: '-1', + createdAt: 1538654776456, + updatedAt: 1538654776456, + updater: '-1', + active: true, + deletedAt: null } } } + */ + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/replace/snippets/replace.test.yml b/doc/6/controllers/document/replace/snippets/replace.test.yml new file mode 100644 index 000000000..2159e6a89 --- /dev/null +++ b/doc/6/controllers/document/replace/snippets/replace.test.yml @@ -0,0 +1,13 @@ +name: document#replace +description: Replace a document +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/search/index.md b/doc/6/controllers/document/search/index.md new file mode 100644 index 000000000..d55ddf8e3 --- /dev/null +++ b/doc/6/controllers/document/search/index.md @@ -0,0 +1,59 @@ +--- +code: true +type: page +title: search +description: Search for documents +--- + +# search + +Searches documents. + +There is a limit to how many documents can be returned by a single search query. +That limit is by default set at 10000 documents, and you can't get over it even with the from and size pagination options. + +:::info +When processing a large number of documents (i.e. more than 1000), it is advised to paginate the results using [SearchResult.next](/sdk/js/6/core-classes/search-result/next/) rather than increasing the size parameter. +::: + +
+ +```js +search(index, collection, [query], [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `query` | 
object
| Search query | +| `options` | 
object
| Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `from` | 
number

(`0`) | Offset of the first document to fetch | +| `size` | 
number

(`10`) | Maximum number of documents to retrieve per page | +| `scroll` | 
string

(`""`) | When set, gets a forward-only cursor having its ttl set to the given value (ie `30s`; cf [elasticsearch time limits](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/common-options.html#time-units)) | + +## Body properties + +### Optional: + +- `query`: the search query itself, using the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl.html) syntax. +- `aggregations`: control how the search results should be [aggregated](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-aggregations.html) +- `sort`: contains a list of fields, used to [sort search results](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-sort.html), in order of importance. + +An empty body matches all documents in the queried collection. + +## Resolves + +Resolves to a [SearchResult](/sdk/js/6/core-classes/search-result) object. + +## Usage + +<<< ./snippets/search.js diff --git a/doc/6/controllers/document/search/snippets/search.js b/doc/6/controllers/document/search/snippets/search.js new file mode 100644 index 000000000..97d037cd2 --- /dev/null +++ b/doc/6/controllers/document/search/snippets/search.js @@ -0,0 +1,61 @@ +const suv = { category: 'suv' }; +const limousine = { category: 'limousine' }; + +try { + const requests = []; + + for (let i = 0; i < 5; i++) { + requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', suv)); + } + for (let i = 0; i < 10; i++) { + requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', limousine)); + } + await Promise.all(requests); + + await kuzzle.index.refresh('nyc-open-data'); + + const results = await kuzzle.document.search( + 'nyc-open-data', + 'yellow-taxi', + { + query: { + match: { + category: 'suv' + } + } + } + ); + + console.log(results); + /* + { + "aggregations": undefined, + "hits": [ + { + "_index": "nyc-open-data", + "_type": "yellow-taxi", + "_id": "AWgi6A1POQUM6ucJ3q06", + "_score": 0.046520017, + "_source": { + "category": "suv", + "_kuzzle_info": { + "author": "-1", + "createdAt": 1546773859655, + "updatedAt": null, + "updater": null, + "active": true, + "deletedAt": null + } + } + }, + ... + ] + }, + "total": 5, + "fetched": 5, + "scroll_id": undefined + */ + console.log(`Successfully retrieved ${results.total} documents`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/search/snippets/search.test.yml b/doc/6/controllers/document/search/snippets/search.test.yml new file mode 100644 index 000000000..be1107e88 --- /dev/null +++ b/doc/6/controllers/document/search/snippets/search.test.yml @@ -0,0 +1,13 @@ +name: document#search +description: Search for documents +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Successfully retrieved 5 documents +sdk: js +version: 6 diff --git a/doc/6/controllers/document/update/index.md b/doc/6/controllers/document/update/index.md new file mode 100644 index 000000000..a2587af85 --- /dev/null +++ b/doc/6/controllers/document/update/index.md @@ -0,0 +1,45 @@ +--- +code: true +type: page +title: update +description: Update a document +--- + +# update + +Updates a document content. + +Conflicts may occur if the same document gets updated multiple times within a short timespan, in a database cluster. +You can set the `retryOnConflict` optional argument (with a retry count), to tell Kuzzle to retry the failing updates the specified amount of times before rejecting the request with an error. + +
+ +```js +update(index, collection, id, document, [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | ----------------------------------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `id` | 
string
| Document ID | +| `document` | 
object
| Partial content of the document to update | +| `options` | 
object
| Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | +| `refresh` | 
string

(`""`) | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) | +| `retryOnConflict` | 
int

(`0`) | The number of times the database layer should retry in case of version conflict | + +## Resolves + +Resolves to an object containing the the document update result. + +## Usage + +<<< ./snippets/update.js diff --git a/doc/6/controllers/document/update/snippets/update.js b/doc/6/controllers/document/update/snippets/update.js new file mode 100644 index 000000000..76d587a5f --- /dev/null +++ b/doc/6/controllers/document/update/snippets/update.js @@ -0,0 +1,27 @@ +try { + await kuzzle.document.create( + 'nyc-open-data', + 'yellow-taxi', + { capacity: 4 }, + 'some-id' + ); + + const response = await kuzzle.document.update( + 'nyc-open-data', + 'yellow-taxi', + 'some-id', + { category: 'suv' } + ); + + console.log(response); + /* + { _index: 'nyc-open-data', + _type: 'yellow-taxi', + _id: 'some-id', + _version: 2, + result: 'updated', + _shards: { total: 2, successful: 1, failed: 0 } } + */ +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/document/update/snippets/update.test.yml b/doc/6/controllers/document/update/snippets/update.test.yml new file mode 100644 index 000000000..de65fb652 --- /dev/null +++ b/doc/6/controllers/document/update/snippets/update.test.yml @@ -0,0 +1,14 @@ +name: document#update +description: Update a document +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: "result: 'updated'" + +sdk: js +version: 6 diff --git a/doc/6/controllers/document/validate/index.md b/doc/6/controllers/document/validate/index.md new file mode 100644 index 000000000..e274a21c1 --- /dev/null +++ b/doc/6/controllers/document/validate/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: validate +description: Validate a document +--- + +# validate + +Validates data against existing validation rules. + +Note that if no validation specifications are set for the ``/``, the document will always be valid. + +This request does **not** store or publish the document. + +
+ +```js +validate(index, collection, document, [options]); +``` + +| Argument | Type | Description | +| ------------ | ----------------- | -------------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `document` | 
object
| Document to validate | +| `options` | 
object
| Query options | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to a boolean value set to true if the document is valid and false otherwise. + +## Usage + +<<< ./snippets/validate.js diff --git a/doc/6/controllers/document/validate/snippets/validate.js b/doc/6/controllers/document/validate/snippets/validate.js new file mode 100644 index 000000000..b2073205c --- /dev/null +++ b/doc/6/controllers/document/validate/snippets/validate.js @@ -0,0 +1,13 @@ +try { + const valid = await kuzzle.document.validate( + 'nyc-open-data', + 'yellow-taxi', + { capacity: 4 } + ); + + if (valid) { + console.log('Success'); + } +} catch (error) { + console.error(error.message); +} \ No newline at end of file diff --git a/doc/6/controllers/document/validate/snippets/validate.test.yml b/doc/6/controllers/document/validate/snippets/validate.test.yml new file mode 100644 index 000000000..7de251334 --- /dev/null +++ b/doc/6/controllers/document/validate/snippets/validate.test.yml @@ -0,0 +1,14 @@ +name: document#validate +description: Validate a document +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/index.md b/doc/6/controllers/index.md new file mode 100644 index 000000000..18fd371b3 --- /dev/null +++ b/doc/6/controllers/index.md @@ -0,0 +1,7 @@ +--- +code: false +type: branch +order: 400 +title: Controllers +description: Javascript SDK v6.x controllers +--- diff --git a/doc/6/controllers/index/create/index.md b/doc/6/controllers/index/create/index.md new file mode 100644 index 000000000..6fd496175 --- /dev/null +++ b/doc/6/controllers/index/create/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: create +description: Creates an index +--- + +# create + +Creates a new index. + +
+ +```js +create(index, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `index` | 
string
| Index name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to an `object` containing the index creation status + +| Name | Type | Description | +| --------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- | +| `acknowledged` | 
boolean
| Indicates whether the index was successfully created in the Elastic cluster | +| `shards_acknowledged` | 
boolean
| Indicates whether the requisite number of shard copies were started for each shard in the index before timing out | + +## Usage + +<<< ./snippets/create.js diff --git a/doc/6/controllers/index/create/snippets/create.js b/doc/6/controllers/index/create/snippets/create.js new file mode 100644 index 000000000..e1ce98080 --- /dev/null +++ b/doc/6/controllers/index/create/snippets/create.js @@ -0,0 +1,12 @@ +try { + const response = await kuzzle.index.create('nyc-open-data'); + console.log(response); + /* + { acknowledged: true, + shards_acknowledged: true } + */ + + console.log('Index created'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/index/create/snippets/create.test.yml b/doc/6/controllers/index/create/snippets/create.test.yml new file mode 100644 index 000000000..9437cac16 --- /dev/null +++ b/doc/6/controllers/index/create/snippets/create.test.yml @@ -0,0 +1,12 @@ +--- +name: index#create +description: Creates a new index +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: default +expected: + - "acknowledged: true" + - "Index created" +sdk: js +version: 6 diff --git a/doc/6/controllers/index/delete/index.md b/doc/6/controllers/index/delete/index.md new file mode 100644 index 000000000..29e082d6d --- /dev/null +++ b/doc/6/controllers/index/delete/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: delete +description: Deletes an index +--- + +# delete + +Deletes a index. + +
+ +```js +delete (index, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `index` | 
string
| Index name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves if the index was successfully deleted in the Elasticsearch cluster. + +## Usage + +<<< ./snippets/delete.js diff --git a/doc/6/controllers/index/delete/snippets/delete.js b/doc/6/controllers/index/delete/snippets/delete.js new file mode 100644 index 000000000..ee0771bf9 --- /dev/null +++ b/doc/6/controllers/index/delete/snippets/delete.js @@ -0,0 +1,7 @@ +try { + kuzzle.index.delete('nyc-open-data'); + + console.log('Index deleted'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/index/delete/snippets/delete.test.yml b/doc/6/controllers/index/delete/snippets/delete.test.yml new file mode 100644 index 000000000..75385676a --- /dev/null +++ b/doc/6/controllers/index/delete/snippets/delete.test.yml @@ -0,0 +1,11 @@ +--- +name: index#delete +description: Deletes an index +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create + after: +template: default +expected: Index deleted + +sdk: js +version: 6 diff --git a/doc/6/controllers/index/exists/index.md b/doc/6/controllers/index/exists/index.md new file mode 100644 index 000000000..c16e4e312 --- /dev/null +++ b/doc/6/controllers/index/exists/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: exists +description: Check for index existence +--- + +# exists + +Checks if the given index exists. + +
+ +```js +exists(index, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `index` | 
string
| Index name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to a `boolean` that indicate whether the index exists or not. + +## Usage + +<<< ./snippets/exists.js diff --git a/doc/6/controllers/index/exists/snippets/exists.js b/doc/6/controllers/index/exists/snippets/exists.js new file mode 100644 index 000000000..5fdc1199d --- /dev/null +++ b/doc/6/controllers/index/exists/snippets/exists.js @@ -0,0 +1,11 @@ +try { + const exists = await kuzzle.index.exists('nyc-open-data'); + + if (exists === true) { + console.log('Index exists'); + } else { + console.log('Index does not exists'); + } +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/index/exists/snippets/exists.test.yml b/doc/6/controllers/index/exists/snippets/exists.test.yml new file mode 100644 index 000000000..55257010d --- /dev/null +++ b/doc/6/controllers/index/exists/snippets/exists.test.yml @@ -0,0 +1,11 @@ +--- +name: index#exists +description: Tests if an index exists +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create + after: +template: default +expected: Index exists + +sdk: js +version: 6 diff --git a/doc/6/controllers/index/get-auto-refresh/index.md b/doc/6/controllers/index/get-auto-refresh/index.md new file mode 100644 index 000000000..46c82aa47 --- /dev/null +++ b/doc/6/controllers/index/get-auto-refresh/index.md @@ -0,0 +1,49 @@ +--- +code: true +type: page +title: getAutoRefresh +description: Returns the status of autorefresh flag +--- + +# getAutoRefresh + +This action returns the current autorefresh status of a index. + +Each index has an autorefresh flag. +When set to true, each write request triggers a [refresh](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/docs-refresh.html) action in Elasticsearch. +Without a refresh after a write request, the documents may not be immediately visible in search. + +:::info +A refresh operation comes with some performance costs. +While forcing the autoRefresh can be convenient on a development or test environment, +we recommend that you avoid using it in production or at least carefully monitor its implications before using it. +::: + +
+ +```js +getAutoRefresh(index, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `index` | 
string
| Index name | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to a `boolean` that indicate the status of the **autoRefresh** flag. + +## Usage + +<<< ./snippets/getAutoRefresh.js diff --git a/doc/6/controllers/index/get-auto-refresh/snippets/getAutoRefresh.js b/doc/6/controllers/index/get-auto-refresh/snippets/getAutoRefresh.js new file mode 100644 index 000000000..0197ea180 --- /dev/null +++ b/doc/6/controllers/index/get-auto-refresh/snippets/getAutoRefresh.js @@ -0,0 +1,7 @@ +try { + const status = await kuzzle.index.getAutoRefresh('nyc-open-data'); + + console.log(`autorefresh is ${status}`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/index/get-auto-refresh/snippets/getAutoRefresh.test.yml b/doc/6/controllers/index/get-auto-refresh/snippets/getAutoRefresh.test.yml new file mode 100644 index 000000000..e8117816b --- /dev/null +++ b/doc/6/controllers/index/get-auto-refresh/snippets/getAutoRefresh.test.yml @@ -0,0 +1,11 @@ +--- +name: index#getAutoRefresh +description: Return autorefresh status for index +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data && curl -X POST kuzzle:7512/nyc-open-data/_create + after: +template: default +expected: autorefresh is false + +sdk: js +version: 6 diff --git a/doc/6/controllers/index/index.md b/doc/6/controllers/index/index.md new file mode 100644 index 000000000..a9e958562 --- /dev/null +++ b/doc/6/controllers/index/index.md @@ -0,0 +1,6 @@ +--- +code: true +type: branch +title: index +description: index controller documentation +--- diff --git a/doc/6/controllers/index/list/index.md b/doc/6/controllers/index/list/index.md new file mode 100644 index 000000000..8e0cdb985 --- /dev/null +++ b/doc/6/controllers/index/list/index.md @@ -0,0 +1,38 @@ +--- +code: true +type: page +title: list +description: Lists the indexes +--- + +# list + +Returns the complete list of indexes. + +
+ +```js +list([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to an array of index names. + +## Usage + +<<< ./snippets/list.js diff --git a/doc/6/controllers/index/list/snippets/list.js b/doc/6/controllers/index/list/snippets/list.js new file mode 100644 index 000000000..3a05ff38e --- /dev/null +++ b/doc/6/controllers/index/list/snippets/list.js @@ -0,0 +1,11 @@ +try { + const indexes = await kuzzle.index.list(); + console.log(indexes); + /* + [ 'nyc-open-data', 'mtp-open-data' ] + */ + + console.log(`Kuzzle contains ${indexes.length} indexes`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/index/list/snippets/list.test.yml b/doc/6/controllers/index/list/snippets/list.test.yml new file mode 100644 index 000000000..6981feadf --- /dev/null +++ b/doc/6/controllers/index/list/snippets/list.test.yml @@ -0,0 +1,14 @@ +--- +name: index#list +description: Lists indexes handled by kuzzle +hooks: + before: | + curl -X POST kuzzle:7512/admin/_resetDatabase + curl -X POST kuzzle:7512/nyc-open-data/_create + curl -X POST kuzzle:7512/mtp-open-data/_create + after: +template: default +expected: Kuzzle contains 2 indexes + +sdk: js +version: 6 diff --git a/doc/6/controllers/index/m-delete/index.md b/doc/6/controllers/index/m-delete/index.md new file mode 100644 index 000000000..fbd825509 --- /dev/null +++ b/doc/6/controllers/index/m-delete/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: mDelete +description: Deletes multiple indexes +--- + +# mDelete + +Deletes multiple indexes. + +
+ +```js +mDelete(indexes, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ----------------------------- | +| `indexes` | 
string[]
| List of index names to delete | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to an array of Successfully deleted indexes. + +## Usage + +<<< ./snippets/mDelete.js diff --git a/doc/6/controllers/index/m-delete/snippets/mDelete.js b/doc/6/controllers/index/m-delete/snippets/mDelete.js new file mode 100644 index 000000000..be18a7a57 --- /dev/null +++ b/doc/6/controllers/index/m-delete/snippets/mDelete.js @@ -0,0 +1,11 @@ +try { + const indexes = await kuzzle.index.mDelete(['nyc-open-data', 'mtp-open-data']); + console.log(indexes); + /* + [ 'nyc-open-data', 'mtp-open-data' ] + */ + + console.log(`Successfully deleted ${indexes.length} indexes`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/index/m-delete/snippets/mDelete.test.yml b/doc/6/controllers/index/m-delete/snippets/mDelete.test.yml new file mode 100644 index 000000000..8f9334ad1 --- /dev/null +++ b/doc/6/controllers/index/m-delete/snippets/mDelete.test.yml @@ -0,0 +1,13 @@ +--- +name: index#mDelete +description: Delete multiple indexes +hooks: + before: | + curl -X POST kuzzle:7512/nyc-open-data/_create + curl -X POST kuzzle:7512/mtp-open-data/_create + after: +template: default +expected: Successfully deleted 2 indexes + +sdk: js +version: 6 diff --git a/doc/6/controllers/index/refresh-internal/index.md b/doc/6/controllers/index/refresh-internal/index.md new file mode 100644 index 000000000..e09917b8d --- /dev/null +++ b/doc/6/controllers/index/refresh-internal/index.md @@ -0,0 +1,48 @@ +--- +code: true +type: page +title: refreshInternal +description: Forces an immediate reindexation of Kuzzle internal storage. +--- + +# refreshInternal + +When writing or deleting security and internal documents (users, roles, profiles, configuration, etc.) in Kuzzle, the update needs to be indexed before being reflected in the search index. + +The `refreshInternal` action forces a [refresh](//sdk/js/6/controllers/index/refresh), on the internal index, making the documents available to search immediately. + +:::info +A refresh operation comes with some performance costs. + +From the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/docs-refresh.html): +> "While a refresh is much lighter than a commit, it still has a performance cost. A manual refresh can be useful when writing tests, but don’t do a manual refresh every time you index a document in production; it will hurt your performance. Instead, your application needs to be aware of the near real-time nature of Elasticsearch and make allowances for it." + +::: + +## Arguments + +```js +refreshInternal([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to a `boolean` containing the refresh status. + +## Usage + +<<< ./snippets/refreshInternal.js diff --git a/doc/6/controllers/index/refresh-internal/snippets/refreshInternal.js b/doc/6/controllers/index/refresh-internal/snippets/refreshInternal.js new file mode 100644 index 000000000..4febc0507 --- /dev/null +++ b/doc/6/controllers/index/refresh-internal/snippets/refreshInternal.js @@ -0,0 +1,9 @@ +try { + const success = await kuzzle.index.refreshInternal(); + + if (success) { + console.log('Internal index successfully refreshed'); + } +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/index/refresh-internal/snippets/refreshInternal.test.yml b/doc/6/controllers/index/refresh-internal/snippets/refreshInternal.test.yml new file mode 100644 index 000000000..372fe4208 --- /dev/null +++ b/doc/6/controllers/index/refresh-internal/snippets/refreshInternal.test.yml @@ -0,0 +1,11 @@ +--- +name: index#refreshInternal +description: Forces an immediate reindexation of Kuzzle internal storage. +hooks: + before: + after: +template: default +expected: Internal index successfully refreshed + +sdk: js +version: 6 diff --git a/doc/6/controllers/index/refresh/index.md b/doc/6/controllers/index/refresh/index.md new file mode 100644 index 000000000..cb338cfe4 --- /dev/null +++ b/doc/6/controllers/index/refresh/index.md @@ -0,0 +1,52 @@ +--- +code: true +type: page +title: refresh +description: Forces an Elasticsearch search index update +--- + +# refresh + +When writing or deleting documents in Kuzzle, the update needs to be indexed before being available in search results. + +:::info +A refresh operation comes with some performance costs. + +From the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/docs-refresh.html): +> "While a refresh is much lighter than a commit, it still has a performance cost. A manual refresh can be useful when writing tests, but don’t do a manual refresh every time you index a document in production; it will hurt your performance. Instead, your application needs to be aware of the near real-time nature of Elasticsearch and make allowances for it." + +::: + +
+ +```js +refresh(index, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to an `object` containing the refresh status on shards. + +| Name | Type | Description | +| ------------ | ----------------- | ----------------------------- | +| `total` | 
number
| Total number of shards | +| `successful` | 
number
| Successfully refreshed shards | +| `failed` | 
number
| Shards that failed to refresh | + +## Usage + +<<< ./snippets/refresh.js diff --git a/doc/6/controllers/index/refresh/snippets/refresh.js b/doc/6/controllers/index/refresh/snippets/refresh.js new file mode 100644 index 000000000..97190974a --- /dev/null +++ b/doc/6/controllers/index/refresh/snippets/refresh.js @@ -0,0 +1,11 @@ +try { + const status = await kuzzle.index.refresh('nyc-open-data'); + console.log(status); + /* + { total: 5, successful: 5, failed: 0 } + */ + + console.log(`${status.failed} shards fail to refresh`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/index/refresh/snippets/refresh.test.yml b/doc/6/controllers/index/refresh/snippets/refresh.test.yml new file mode 100644 index 000000000..2121be65c --- /dev/null +++ b/doc/6/controllers/index/refresh/snippets/refresh.test.yml @@ -0,0 +1,11 @@ +--- +name: index#refresh +description: Forces an Elasticsearch search index update +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create + after: +template: default +expected: 0 shards fail to refresh + +sdk: js +version: 6 diff --git a/doc/6/controllers/index/set-auto-refresh/index.md b/doc/6/controllers/index/set-auto-refresh/index.md new file mode 100644 index 000000000..9f21a040d --- /dev/null +++ b/doc/6/controllers/index/set-auto-refresh/index.md @@ -0,0 +1,50 @@ +--- +code: true +type: page +title: setAutoRefresh +description: Set the autorefresh flag +--- + +# setAutoRefresh + +The setAutoRefresh action allows to set the autorefresh flag for a index. + +Each index has an autorefresh flag. +When set to true, each write request trigger a [refresh](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-refresh.html) action on Elasticsearch. +Without a refresh after a write request, the documents may not be immediately visible in search. + +:::info +A refresh operation comes with performance costs. +While forcing the autoRefresh can be convenient on a development or test environment, +we recommend that you avoid using it in production or at least carefully monitor its implications before using it. +::: + +
+ +```js +setAutoRefresh(index, autoRefresh, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------- | ------------------ | ----------------- | +| `index` | 
string
| Index name | +| `autoRefresh` | 
boolean
| AutoRefresh value | +| `options` | 
number
| Query options | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolves to a `boolean` representing the new value of the autorefresh flag. + +## Usage + +<<< ./snippets/setAutoRefresh.js diff --git a/doc/6/controllers/index/set-auto-refresh/snippets/setAutoRefresh.js b/doc/6/controllers/index/set-auto-refresh/snippets/setAutoRefresh.js new file mode 100644 index 000000000..75d8736de --- /dev/null +++ b/doc/6/controllers/index/set-auto-refresh/snippets/setAutoRefresh.js @@ -0,0 +1,9 @@ +try { + const autoRefresh = await kuzzle.index.setAutoRefresh('nyc-open-data', true); + + if (autoRefresh === true) { + console.log(`Autorefresh flag is set to true`); + } +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/index/set-auto-refresh/snippets/setAutoRefresh.test.yml b/doc/6/controllers/index/set-auto-refresh/snippets/setAutoRefresh.test.yml new file mode 100644 index 000000000..3a89cb389 --- /dev/null +++ b/doc/6/controllers/index/set-auto-refresh/snippets/setAutoRefresh.test.yml @@ -0,0 +1,13 @@ +--- +name: index#setAutoRefresh +description: Set the autorefresh flag for the index +hooks: + before: | + curl -X DELETE kuzzle:7512/nyc-open-data + curl -X POST kuzzle:7512/nyc-open-data/_create + after: +template: default +expected: Autorefresh flag is set to true + +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/append/index.md b/doc/6/controllers/ms/append/index.md new file mode 100644 index 000000000..bf8994f93 --- /dev/null +++ b/doc/6/controllers/ms/append/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: append +--- + +# append + +Appends a value to a key. If the key does not exist, it is created. + +[[_Redis documentation_]](https://redis.io/commands/append) + +## Arguments + +```js +append(key, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `value` | 
string
| Value to append | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Returns the updated value length. + +## Usage + +<<< ./snippets/append.js diff --git a/doc/6/controllers/ms/append/snippets/append.js b/doc/6/controllers/ms/append/snippets/append.js new file mode 100644 index 000000000..01c747745 --- /dev/null +++ b/doc/6/controllers/ms/append/snippets/append.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.set('hw', 'Hello'); + + await kuzzle.ms.append('hw', ' World'); + + // Prints: Hello World + console.log(await kuzzle.ms.get('hw')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/append/snippets/append.test.yml b/doc/6/controllers/ms/append/snippets/append.test.yml new file mode 100644 index 000000000..1b778932d --- /dev/null +++ b/doc/6/controllers/ms/append/snippets/append.test.yml @@ -0,0 +1,9 @@ +name: ms#append +description: Appends a value to a key. If the key does not exist, it is created +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: Hello World +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/bitcount/index.md b/doc/6/controllers/ms/bitcount/index.md new file mode 100644 index 000000000..db719f134 --- /dev/null +++ b/doc/6/controllers/ms/bitcount/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: bitcount +--- + +# bitcount + +Counts the number of set bits (population counting) in a string. + +[[_Redis documentation_]](https://redis.io/commands/bitcount) + +## Arguments + +```js +bitcount(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `end` | 
integer
| Count ends at the provided offset | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | +| `start` | 
integer
| Count starts at the provided offset | + +## Resolve + +Resolves to the number of set bits. + +## Usage + +<<< ./snippets/bitcount.js diff --git a/doc/6/controllers/ms/bitcount/snippets/bitcount.js b/doc/6/controllers/ms/bitcount/snippets/bitcount.js new file mode 100644 index 000000000..0d598a8df --- /dev/null +++ b/doc/6/controllers/ms/bitcount/snippets/bitcount.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.set('key', 'foobar'); + + // Prints: 26 + console.log(await kuzzle.ms.bitcount('key')); + + // Prints: 4 + console.log(await kuzzle.ms.bitcount('key', {start: 0, end: 0})); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/bitcount/snippets/bitcount.test.yml b/doc/6/controllers/ms/bitcount/snippets/bitcount.test.yml new file mode 100644 index 000000000..887b5762e --- /dev/null +++ b/doc/6/controllers/ms/bitcount/snippets/bitcount.test.yml @@ -0,0 +1,11 @@ +name: ms#bitcount +description: Counts the number of set bits (population counting) in a string +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - 26 + - 4 +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/bitop/index.md b/doc/6/controllers/ms/bitop/index.md new file mode 100644 index 000000000..60a5eb03f --- /dev/null +++ b/doc/6/controllers/ms/bitop/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: bitop +--- + +# bitop + +Performs a bitwise operation between multiple keys (containing string values) and stores the result in the destination key. + +[[_Redis documentation_]](https://redis.io/commands/bitop) + +## Arguments + +```js +bitop(key, operation, keys, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------- | ----------------------------------------------------------------------------------------- | +| `key` | 
string
| Key | +| `operation` | 
string
| The bitwise operand to use to combine keys.
Allowed values: `AND`, `NOT`, `OR`, `XOR` | +| `keys` | 
string[]
| The list of keys to combine | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the new destination key length. + +## Usage + +<<< ./snippets/bitop.js diff --git a/doc/6/controllers/ms/bitop/snippets/bitop.js b/doc/6/controllers/ms/bitop/snippets/bitop.js new file mode 100644 index 000000000..47bb01c41 --- /dev/null +++ b/doc/6/controllers/ms/bitop/snippets/bitop.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.set('key1', 'foobar'); + await kuzzle.ms.set('key2', 'abcdef'); + + await kuzzle.ms.bitop('dest', 'AND', ['key1', 'key2']); + + // Prints: `bc`ab + console.log(await kuzzle.ms.get('dest')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/bitop/snippets/bitop.test.yml b/doc/6/controllers/ms/bitop/snippets/bitop.test.yml new file mode 100644 index 000000000..34f2b6513 --- /dev/null +++ b/doc/6/controllers/ms/bitop/snippets/bitop.test.yml @@ -0,0 +1,9 @@ +name: ms#bitop +description: Performs a bitwise operation between multiple keys +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "`bc`ab" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/bitpos/index.md b/doc/6/controllers/ms/bitpos/index.md new file mode 100644 index 000000000..1c3ba80db --- /dev/null +++ b/doc/6/controllers/ms/bitpos/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: bitpos +--- + +# bitpos + +Returns the position of the first bit set to 1 or 0 in a string, or in a substring. + +[[_Redis documentation_]](https://redis.io/commands/bitpos) + +## Arguments + +```js +bitpos(key, bit, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ---------------------------------------------- | +| `key` | 
string
| Key | +| `bit` | 
integer
| Bit to look for.
Accepted values: `0`, `1` | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `end` | 
integer
| Search ends at the provided offset | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | +| `start` | 
integer
| Search starts at the provided offset | + +## Resolve + +Resolves to the position of the first bit found matching the searched value. + +## Usage + +<<< ./snippets/bitpos.js diff --git a/doc/6/controllers/ms/bitpos/snippets/bitpos.js b/doc/6/controllers/ms/bitpos/snippets/bitpos.js new file mode 100644 index 000000000..a5250bbbe --- /dev/null +++ b/doc/6/controllers/ms/bitpos/snippets/bitpos.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('key', '\x00\x00\x01'); + + // Prints: 23 + console.log(await kuzzle.ms.bitpos('key', 1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/bitpos/snippets/bitpos.test.yml b/doc/6/controllers/ms/bitpos/snippets/bitpos.test.yml new file mode 100644 index 000000000..42aa3d157 --- /dev/null +++ b/doc/6/controllers/ms/bitpos/snippets/bitpos.test.yml @@ -0,0 +1,9 @@ +name: ms#bitpos +description: Returns the position of the first bit set to 1 or 0 in a string, or in a substring +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: 23 +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/dbsize/index.md b/doc/6/controllers/ms/dbsize/index.md new file mode 100644 index 000000000..24d1c804d --- /dev/null +++ b/doc/6/controllers/ms/dbsize/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: dbsize +--- + +# dbsize + +Returns the number of keys in the application database. + +[[_Redis documentation_]](https://redis.io/commands/dbsize) + +## Arguments + +```js +dbsize([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of found keys. + +## Usage + +<<< ./snippets/dbsize.js diff --git a/doc/6/controllers/ms/dbsize/snippets/dbsize.js b/doc/6/controllers/ms/dbsize/snippets/dbsize.js new file mode 100644 index 000000000..25df85e10 --- /dev/null +++ b/doc/6/controllers/ms/dbsize/snippets/dbsize.js @@ -0,0 +1,6 @@ +try { + const size = await kuzzle.ms.dbsize(); + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/dbsize/snippets/dbsize.test.yml b/doc/6/controllers/ms/dbsize/snippets/dbsize.test.yml new file mode 100644 index 000000000..21811fa67 --- /dev/null +++ b/doc/6/controllers/ms/dbsize/snippets/dbsize.test.yml @@ -0,0 +1,9 @@ +name: ms#dbsize +description: Returns the number of keys in the application database +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: Success +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/decr/index.md b/doc/6/controllers/ms/decr/index.md new file mode 100644 index 000000000..9492718e1 --- /dev/null +++ b/doc/6/controllers/ms/decr/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: decr +--- + +# decr + +Decrements the number stored at `key` by 1. If the key does not exist, it is set to 0 before performing the operation. + +[[_Redis documentation_]](https://redis.io/commands/decr) + +## Arguments + +```js +decr(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated key value. + +## Usage + +<<< ./snippets/decr.js diff --git a/doc/6/controllers/ms/decr/snippets/decr.js b/doc/6/controllers/ms/decr/snippets/decr.js new file mode 100644 index 000000000..681cb503a --- /dev/null +++ b/doc/6/controllers/ms/decr/snippets/decr.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('val', 43); + + // Prints: 42 + console.log(await kuzzle.ms.decr('val')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/decr/snippets/decr.test.yml b/doc/6/controllers/ms/decr/snippets/decr.test.yml new file mode 100644 index 000000000..f515ac10c --- /dev/null +++ b/doc/6/controllers/ms/decr/snippets/decr.test.yml @@ -0,0 +1,9 @@ +name: ms#decr +description: Decrements the number stored at `key` by 1 +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: 42 +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/decrby/index.md b/doc/6/controllers/ms/decrby/index.md new file mode 100644 index 000000000..1a5301d88 --- /dev/null +++ b/doc/6/controllers/ms/decrby/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: decrby +--- + +# decrby + +Decrements the number stored at `key` by a provided integer value. If the key does not exist, it is set to 0 before performing the operation. + +[[_Redis documentation_]](https://redis.io/commands/decrby) + +## Arguments + +```js +decrby(key, decrement, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------ | ------------------------ | +| `key` | 
string
| Key | +| `decrement` | 
integer
| Decrement value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated key value. + +## Usage + +<<< ./snippets/decrby.js diff --git a/doc/6/controllers/ms/decrby/snippets/decrby.js b/doc/6/controllers/ms/decrby/snippets/decrby.js new file mode 100644 index 000000000..49bb332b1 --- /dev/null +++ b/doc/6/controllers/ms/decrby/snippets/decrby.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('val', 12); + + // Prints: 42 + console.log(await kuzzle.ms.decrby('val', -30)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/decrby/snippets/decrby.test.yml b/doc/6/controllers/ms/decrby/snippets/decrby.test.yml new file mode 100644 index 000000000..63ce294a4 --- /dev/null +++ b/doc/6/controllers/ms/decrby/snippets/decrby.test.yml @@ -0,0 +1,9 @@ +name: ms#decrby +description: Decrements the number stored at key by a provided integer value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: 42 +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/del/index.md b/doc/6/controllers/ms/del/index.md new file mode 100644 index 000000000..ce4ad6873 --- /dev/null +++ b/doc/6/controllers/ms/del/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: del +--- + +# del + +Deletes a list of keys. + +[[_Redis documentation_]](https://redis.io/commands/del) + +## Arguments + +```js +del(keys, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `keys` | 
string[]
| Keys to delete | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of deleted keys. + +## Usage + +<<< ./snippets/del.js diff --git a/doc/6/controllers/ms/del/snippets/del.js b/doc/6/controllers/ms/del/snippets/del.js new file mode 100644 index 000000000..e6b0ea88e --- /dev/null +++ b/doc/6/controllers/ms/del/snippets/del.js @@ -0,0 +1,15 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + + // Prints: 1 + console.log(await kuzzle.ms.exists(['foo'])); + + await kuzzle.ms.del(['foo']); + + // Prints: 0 + console.log(await kuzzle.ms.exists(['foo'])); + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/del/snippets/del.test.yml b/doc/6/controllers/ms/del/snippets/del.test.yml new file mode 100644 index 000000000..fc4ff56b2 --- /dev/null +++ b/doc/6/controllers/ms/del/snippets/del.test.yml @@ -0,0 +1,9 @@ +name: ms#del +description: Deletes a list of keys +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: 0 +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/exists/index.md b/doc/6/controllers/ms/exists/index.md new file mode 100644 index 000000000..ce8355dc8 --- /dev/null +++ b/doc/6/controllers/ms/exists/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: exists +--- + +# exists + +Checks if the specified keys exist in the database. + +[[_Redis documentation_]](https://redis.io/commands/exists) + +## Arguments + +```js +exists(keys, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | --------------------------- | +| `keys` | 
string[]
| Keys to check for existence | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of existing keys. + +## Usage + +<<< ./snippets/exists.js diff --git a/doc/6/controllers/ms/exists/snippets/exists.js b/doc/6/controllers/ms/exists/snippets/exists.js new file mode 100644 index 000000000..3266a19bb --- /dev/null +++ b/doc/6/controllers/ms/exists/snippets/exists.js @@ -0,0 +1,13 @@ +try { + // Prints: 0 + console.log(await kuzzle.ms.exists(['foo'])); + + await kuzzle.ms.set('foo', 'bar'); + + // Prints: 1 + console.log(await kuzzle.ms.exists(['foo'])); + + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/exists/snippets/exists.test.yml b/doc/6/controllers/ms/exists/snippets/exists.test.yml new file mode 100644 index 000000000..8c0752b08 --- /dev/null +++ b/doc/6/controllers/ms/exists/snippets/exists.test.yml @@ -0,0 +1,11 @@ +name: ms#exists +description: Checks if the specified keys exist in the database +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^0$ + - ^1$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/expire/index.md b/doc/6/controllers/ms/expire/index.md new file mode 100644 index 000000000..0c34e8d80 --- /dev/null +++ b/doc/6/controllers/ms/expire/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: expire +--- + +# expire + +Sets a timeout (in seconds) on a key. After the timeout has expired, the key is automatically deleted. + +[[_Redis documentation_]](https://redis.io/commands/expire) + +## Arguments + +```js +expire(key, seconds, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ---------------------------------------- | +| `key` | 
string
| Key | +| `seconds` | 
integer
| Number of seconds before the key expires | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean telling whether the operation was successful or not. + +## Usage + +<<< ./snippets/expire.js diff --git a/doc/6/controllers/ms/expire/snippets/expire.js b/doc/6/controllers/ms/expire/snippets/expire.js new file mode 100644 index 000000000..ff0720951 --- /dev/null +++ b/doc/6/controllers/ms/expire/snippets/expire.js @@ -0,0 +1,13 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + + // Prints: -1 + console.log(await kuzzle.ms.ttl('foo')); + + await kuzzle.ms.expire('foo', 10); + + // Prints: 10 + console.log(await kuzzle.ms.ttl('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/expire/snippets/expire.test.yml b/doc/6/controllers/ms/expire/snippets/expire.test.yml new file mode 100644 index 000000000..fac040455 --- /dev/null +++ b/doc/6/controllers/ms/expire/snippets/expire.test.yml @@ -0,0 +1,11 @@ +name: ms#expire +description: Sets a timeout (in seconds) on a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - -1 + - ^[1-9]+ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/expireat/index.md b/doc/6/controllers/ms/expireat/index.md new file mode 100644 index 000000000..0995e3b00 --- /dev/null +++ b/doc/6/controllers/ms/expireat/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: expireat +--- + +# expireat + +Sets an expiration timestamp on a key. After the timestamp has been reached, the key will automatically be deleted. + +[[_Redis documentation_]](https://redis.io/commands/expireat) + +## Arguments + +```js +expireat(key, timestamp, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------ | ------------------------------------------------------------------------------ | +| `key` | 
string
| Key | +| `timestamp` | 
integer
| Expiration timestamp ([Epoch](https://en.wikipedia.org/wiki/Unix_time) format) | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean telling whether the operation was successful or not. + +## Usage + +<<< ./snippets/expireat.js diff --git a/doc/6/controllers/ms/expireat/snippets/expireat.js b/doc/6/controllers/ms/expireat/snippets/expireat.js new file mode 100644 index 000000000..c40f69d65 --- /dev/null +++ b/doc/6/controllers/ms/expireat/snippets/expireat.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + + // Prints: 1 + console.log(await kuzzle.ms.exists(['foo'])); + + // Oct. 12, 2011 + await kuzzle.ms.expireat('foo', 1318425955); + + // Prints: 0 + console.log(await kuzzle.ms.exists(['foo'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/expireat/snippets/expireat.test.yml b/doc/6/controllers/ms/expireat/snippets/expireat.test.yml new file mode 100644 index 000000000..735ea84da --- /dev/null +++ b/doc/6/controllers/ms/expireat/snippets/expireat.test.yml @@ -0,0 +1,11 @@ +name: ms#expireat +description: Sets an expiration timestamp on a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^1$ + - ^0$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/flushdb/index.md b/doc/6/controllers/ms/flushdb/index.md new file mode 100644 index 000000000..f0c7cd774 --- /dev/null +++ b/doc/6/controllers/ms/flushdb/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: flushdb +--- + +# flushdb + +Empties the database dedicated to client applications (the reserved space for Kuzzle is unaffected). + +[[_Redis documentation_]](https://redis.io/commands/flushdb) + +## Arguments + +```js +flushdb([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to `undefined` once the operation completes. + +## Usage + +<<< ./snippets/flushdb.js diff --git a/doc/6/controllers/ms/flushdb/snippets/flushdb.js b/doc/6/controllers/ms/flushdb/snippets/flushdb.js new file mode 100644 index 000000000..ceb31b43a --- /dev/null +++ b/doc/6/controllers/ms/flushdb/snippets/flushdb.js @@ -0,0 +1,6 @@ +try { + await kuzzle.ms.flushdb(); + console.log('Success'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/flushdb/snippets/flushdb.test.yml b/doc/6/controllers/ms/flushdb/snippets/flushdb.test.yml new file mode 100644 index 000000000..ae2331836 --- /dev/null +++ b/doc/6/controllers/ms/flushdb/snippets/flushdb.test.yml @@ -0,0 +1,9 @@ +name: ms#flushdb +description: Empties the database dedicated to client applications +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: Success +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/geoadd/index.md b/doc/6/controllers/ms/geoadd/index.md new file mode 100644 index 000000000..85899b4f0 --- /dev/null +++ b/doc/6/controllers/ms/geoadd/index.md @@ -0,0 +1,51 @@ +--- +code: true +type: page +title: geoadd +--- + +# geoadd + +Adds geospatial points to the specified key. + +[[_Redis documentation_]](https://redis.io/commands/geoadd) + +## Arguments + +```js +geoadd(key, geopoints, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------- | ------------------------ | +| `key` | 
string
| Key | +| `geopoints` | 
object[]
| List of geopoints to add | +| `options` | 
object
| Optional query arguments | + +### geopoints + +List of objects, each one of those being a geopoint to be added, with the following properties: + +| Properties | Type | Description | +| ---------- | ----------------- | ----------------------------------------- | +| `lat` | 
number
| Latitude | +| `lon` | 
number
| Longitude | +| `name` | 
string
| Unique point name (used as an identifier) | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of points added. + +## Usage + +<<< ./snippets/geoadd.js diff --git a/doc/6/controllers/ms/geoadd/snippets/geoadd.js b/doc/6/controllers/ms/geoadd/snippets/geoadd.js new file mode 100644 index 000000000..7bd4badde --- /dev/null +++ b/doc/6/controllers/ms/geoadd/snippets/geoadd.js @@ -0,0 +1,19 @@ +const kuzzleHQ = { + lon: 3.9109057, + lat: 43.6073913, + name: 'HQ' +}; +const otherHQ = { + lon: 3.897105, + lat: 43.6002203, + name: 'other HQ' +}; + +try { + const result = await kuzzle.ms.geoadd('geofoo', [kuzzleHQ, otherHQ]); + + // Prints: 2 + console.log(result); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/geoadd/snippets/geoadd.test.yml b/doc/6/controllers/ms/geoadd/snippets/geoadd.test.yml new file mode 100644 index 000000000..ab30f799c --- /dev/null +++ b/doc/6/controllers/ms/geoadd/snippets/geoadd.test.yml @@ -0,0 +1,9 @@ +name: ms#geoadd +description: Adds geospatial points to the specified key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: 2 +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/geodist/index.md b/doc/6/controllers/ms/geodist/index.md new file mode 100644 index 000000000..2e07b878f --- /dev/null +++ b/doc/6/controllers/ms/geodist/index.md @@ -0,0 +1,45 @@ +--- +code: true +type: page +title: geodist +--- + +# geodist + +Returns the distance between two geospatial members of a key (see [geoadd](/sdk/js/6/controllers/ms/geoadd)). + +The returned distance is expressed in meters by default. + +[[_Redis documentation_]](https://redis.io/commands/geodist) + +## Arguments + +```js +geodist(key, geopoint1, geopoint2, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ----------------- | -------------------------- | +| `key` | 
string
| Key | +| `geopoint1` | 
string
| First geopoint identifier | +| `geopoint2` | 
string
| Second geopoint identifier | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | +| `unit` | 
string ('m')
| The unit used for the returned calculated distance.
Accepted values: `m`, `km`, `mi`, `ft` | + +## Resolve + +Resolves to the calculated distance. + +## Usage + +<<< ./snippets/geodist.js diff --git a/doc/6/controllers/ms/geodist/snippets/geodist.js b/doc/6/controllers/ms/geodist/snippets/geodist.js new file mode 100644 index 000000000..3d0346846 --- /dev/null +++ b/doc/6/controllers/ms/geodist/snippets/geodist.js @@ -0,0 +1,28 @@ +const kuzzleHQ = { + lon: 3.9109057, + lat: 43.6073913, + name: 'HQ' +}; + +const otherHQ = { + lon: 3.897105, + lat: 43.6002203, + name: 'other HQ' +}; + +try { + await kuzzle.ms.geoadd('geofoo', [kuzzleHQ, otherHQ]); + + // Prints: 1367.8521 + console.log(await kuzzle.ms.geodist('geofoo', 'HQ', 'other HQ')); + + // Prints: 4487.7038 + console.log(await kuzzle.ms.geodist( + 'geofoo', + 'HQ', + 'other HQ', + {unit: 'ft'} + )); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/geodist/snippets/geodist.test.yml b/doc/6/controllers/ms/geodist/snippets/geodist.test.yml new file mode 100644 index 000000000..8b97f33bb --- /dev/null +++ b/doc/6/controllers/ms/geodist/snippets/geodist.test.yml @@ -0,0 +1,11 @@ +name: ms#geodist +description: Returns the distance between two geospatial members of a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - 1367.8521 + - 4487.7038 +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/geohash/index.md b/doc/6/controllers/ms/geohash/index.md new file mode 100644 index 000000000..f807cbb5d --- /dev/null +++ b/doc/6/controllers/ms/geohash/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: geohash +--- + +# geohash + +Converts a key's geopoints (see [geoadd](/sdk/js/6/controllers/ms/geoadd)) into [geohashes](https://en.wikipedia.org/wiki/Geohash). + +[[_Redis documentation_]](https://redis.io/commands/geohash) + +## Arguments + +```js +geohash(key, geopoints, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------- | ---------------------------- | +| `key` | 
string
| Key | +| `geopoints` | 
string[]
| List of geopoints to convert | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an array of converted geohashes, in the same order than the one provided in the query. + +## Usage + +<<< ./snippets/geohash.js diff --git a/doc/6/controllers/ms/geohash/snippets/geohash.js b/doc/6/controllers/ms/geohash/snippets/geohash.js new file mode 100644 index 000000000..b15d82316 --- /dev/null +++ b/doc/6/controllers/ms/geohash/snippets/geohash.js @@ -0,0 +1,20 @@ +const kuzzleHQ = { + lon: 3.9109057, + lat: 43.6073913, + name: 'HQ' +}; + +const otherHQ = { + lon: 3.897105, + lat: 43.6002203, + name: 'other HQ' +}; + +try { + await kuzzle.ms.geoadd('geofoo', [kuzzleHQ, otherHQ]); + + // Prints: [ 'spfb0frz6x0', 'spfb09jv9n0' ] + console.log(await kuzzle.ms.geohash('geofoo', ['HQ', 'other HQ'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/geohash/snippets/geohash.test.yml b/doc/6/controllers/ms/geohash/snippets/geohash.test.yml new file mode 100644 index 000000000..a7c97b3d6 --- /dev/null +++ b/doc/6/controllers/ms/geohash/snippets/geohash.test.yml @@ -0,0 +1,9 @@ +name: ms#geohash +description: Converts a key's geopoints into geohashes +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "[ 'spfb0frz6x0', 'spfb09jv9n0' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/geopos/index.md b/doc/6/controllers/ms/geopos/index.md new file mode 100644 index 000000000..8603ee29c --- /dev/null +++ b/doc/6/controllers/ms/geopos/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: geopos +--- + +# geopos + +Returns the positions of the provided key's members (see [geoadd](/sdk/js/6/controllers/ms/geoadd)). + +[[_Redis documentation_]](https://redis.io/commands/geopos) + +## Arguments + +```js +geopos(key, geopoints, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------- | --------------------------- | +| `key` | 
string
| Key | +| `geopoints` | 
string[]
| List of geopoints to return | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the members positions (`[longitude, latitude]`), in the same order than the one provided in the query. + +## Usage + +<<< ./snippets/geopos.js diff --git a/doc/6/controllers/ms/geopos/snippets/geopos.js b/doc/6/controllers/ms/geopos/snippets/geopos.js new file mode 100644 index 000000000..3eb931671 --- /dev/null +++ b/doc/6/controllers/ms/geopos/snippets/geopos.js @@ -0,0 +1,24 @@ +const kuzzleHQ = { + lon: 3.9109057, + lat: 43.6073913, + name: 'HQ' +}; + +const otherHQ = { + lon: 3.897105, + lat: 43.6002203, + name: 'other HQ' +}; + +try { + await kuzzle.ms.geoadd('geofoo', [kuzzleHQ, otherHQ]); + + // Prints: + // [ + // [ 3.910904824733734, 43.607392252329916 ], + // [ 3.8971075415611267, 43.600221526170145 ] + // ] + console.log(await kuzzle.ms.geopos('geofoo', ['HQ', 'other HQ'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/geopos/snippets/geopos.test.yml b/doc/6/controllers/ms/geopos/snippets/geopos.test.yml new file mode 100644 index 000000000..322cc82c4 --- /dev/null +++ b/doc/6/controllers/ms/geopos/snippets/geopos.test.yml @@ -0,0 +1,11 @@ +name: ms#geopos +description: Returns the positions of the provided key's members +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ \\[ 3.910904824733734, 43.607392252329916 ]," + - "\\[ 3.8971075415611267, 43.600221526170145 ] ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/georadius/index.md b/doc/6/controllers/ms/georadius/index.md new file mode 100644 index 000000000..c605cb6ec --- /dev/null +++ b/doc/6/controllers/ms/georadius/index.md @@ -0,0 +1,56 @@ +--- +code: true +type: page +title: georadius +--- + +# georadius + +Returns the members (added with [geoadd](/sdk/js/6/controllers/ms/geoadd)) of a given key inside the provided geospatial radius. + +[[_Redis documentation_]](https://redis.io/commands/georadius) + +## Arguments + +```js +georadius(key, lon, lat, dist, unit, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------------------------------------------------------------- | +| `key` | 
string
| Key | +| `lon` | 
number
| Longitude of the center | +| `lat` | 
number
| Latitude of the center | +| `dist` | 
number
| Distance from the center | +| `unit` | 
string
| Unit of the distance parameter value.
Allowed values: `m`, `km`, `mi`, `ft` | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ----------- | -------------------------- | -------------------------------------------------------------------------------------- | +| `count` | 
integer
| Limit the number of returned geopoints to the provided value | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | +| `sort` | 
string
| Sort the result by distance, relative to the center.
Allowed values: `ASC`, `DESC` | +| `withcoord` | 
boolean (false)
| Include the position of the matched geopoint in the result | +| `withdist` | 
boolean (false)
| Include the calculated distance from the matched geopoint to center | + +## Resolve + +Resolves to an array of matched geopoints. + +Each returned geopoint is an object with the following properties: + +| Property | Type | Description | +| ------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- | +| `name` | 
string
| Geopoint identifier | +| `coordinates` | 
number[]
| Geopoint coordinates in the following format: `[lon, lat]`. Only available if the option `withcoord` is set | +| `distance` | 
number
| Distance from the center. Only available if the option `withdist` is set | + +## Usage + +<<< ./snippets/georadius.js diff --git a/doc/6/controllers/ms/georadius/snippets/georadius.js b/doc/6/controllers/ms/georadius/snippets/georadius.js new file mode 100644 index 000000000..0dba84211 --- /dev/null +++ b/doc/6/controllers/ms/georadius/snippets/georadius.js @@ -0,0 +1,61 @@ +const kuzzleHQ = { + lon: 3.9109057, + lat: 43.6073913, + name: 'HQ' +}; +const otherHQ = { + lon: 3.897105, + lat: 43.6002203, + name: 'other HQ' +}; + +try { + await kuzzle.ms.geoadd('geofoo', [kuzzleHQ, otherHQ]); + + // Prints: [ { name: 'other HQ' }, { name: 'HQ' } ] + console.log(await kuzzle.ms.georadius( + 'geofoo', + 3.948711, + 43.5764455, + 20, + 'km' + )); + + // Prints: + // [ + // { name: 'other HQ', distance: 4.9271 }, + // { name: 'HQ', distance: 4.596 } + // ] + console.log(await kuzzle.ms.georadius( + 'geofoo', + 3.948711, + 43.5764455, + 20, + 'km', + {withdist: true, sort: 'desc'} + )); + + // Prints: + // [ + // { + // name: 'HQ', + // distance: 4.596, + // coordinates: [ 3.910904824733734, 43.607392252329916 ] + // }, + // { + // name: 'other HQ', + // distance: 4.9271, + // coordinates: [ 3.8971075415611267, 43.600221526170145 ] + // } + // ] + console.log(await kuzzle.ms.georadius( + 'geofoo', + 3.948711, + 43.5764455, + 20, + 'km', + {withcoord: true, withdist: true, sort: 'asc'} + )); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/georadius/snippets/georadius.test.yml b/doc/6/controllers/ms/georadius/snippets/georadius.test.yml new file mode 100644 index 000000000..c3ca8f98b --- /dev/null +++ b/doc/6/controllers/ms/georadius/snippets/georadius.test.yml @@ -0,0 +1,18 @@ +name: ms#georadius +description: Returns the members of a given key inside the provided geospatial radius +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { name: 'other HQ' }, { name: 'HQ' } " + - "\\[ { name: 'other HQ', distance: 4.9271 }," + - " { name: 'HQ', distance: 4.596 } ]" + - "\\[ { name: 'HQ'," + - " distance: 4.596," + - " coordinates: \\[ 3.910904824733734, 43.607392252329916 ] }," + - " { name: 'other HQ'," + - " distance: 4.9271," + - " coordinates: \\[ 3.8971075415611267, 43.600221526170145 ] } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/georadiusbymember/index.md b/doc/6/controllers/ms/georadiusbymember/index.md new file mode 100644 index 000000000..797c931de --- /dev/null +++ b/doc/6/controllers/ms/georadiusbymember/index.md @@ -0,0 +1,55 @@ +--- +code: true +type: page +title: georadiusbymember +--- + +# georadiusbymember + +Returns the members (added with [geoadd](/sdk/js/6/controllers/ms/geoadd)) of a given key inside the provided geospatial radius, centered around one of a key's member. + +[[_Redis documentation_]](https://redis.io/commands/georadiusbymember) + +## Arguments + +```js +georadiusbymember(key, geopoint, dist, unit, [options]); +``` + +
+ +| Arguments | Type | Description | +| ---------- | ----------------- | ------------------------------------------------------------------------------- | +| `key` | 
string
| Key | +| `geopoint` | 
string
| Name of the geopoint to use as the center | +| `dist` | 
number
| Distance from the center | +| `unit` | 
string
| Unit of the distance parameter value.
Allowed values: `m`, `km`, `mi`, `ft` | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ----------- | -------------------------- | -------------------------------------------------------------------------------------- | +| `count` | 
integer
| Limit the number of returned geopoints to the provided value | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | +| `sort` | 
string
| Sort the result by distance, relative to the center.
Allowed values: `ASC`, `DESC` | +| `withcoord` | 
boolean (false)
| Include the position of the matched geopoint in the result | +| `withdist` | 
boolean (false)
| Include the calculated distance from the matched geopoint to center | + +## Resolve + +Resolves to an array of matched geopoints. + +Each returned geopoint is an object with the following properties: + +| Property | Type | Description | +| ------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- | +| `name` | 
string
| Geopoint identifier | +| `coordinates` | 
number[]
| Geopoint coordinates in the following format: `[lon, lat]`. Only available if the option `withcoord` is set | +| `distance` | 
number
| Distance from the center. Only available if the option `withdist` is set | + +## Usage + +<<< ./snippets/georadiusbymember.js diff --git a/doc/6/controllers/ms/georadiusbymember/snippets/georadiusbymember.js b/doc/6/controllers/ms/georadiusbymember/snippets/georadiusbymember.js new file mode 100644 index 000000000..6cb4a07b5 --- /dev/null +++ b/doc/6/controllers/ms/georadiusbymember/snippets/georadiusbymember.js @@ -0,0 +1,58 @@ +const kuzzleHQ = { + lon: 3.9109057, + lat: 43.6073913, + name: 'HQ' +}; +const otherHQ = { + lon: 3.897105, + lat: 43.6002203, + name: 'other HQ' +}; + +try { + await kuzzle.ms.geoadd('geofoo', [kuzzleHQ, otherHQ]); + + // Prints: [ { name: 'other HQ' }, { name: 'HQ' } ] + console.log(await kuzzle.ms.georadiusbymember( + 'geofoo', + 'HQ', + 1500, + 'm' + )); + + // Prints: + // [ + // { name: 'other HQ', distance: 1367.8521 }, + // { name: 'HQ', distance: 0 } + // ] + console.log(await kuzzle.ms.georadiusbymember( + 'geofoo', + 'HQ', + 1500, + 'm', + {withdist: true, sort: 'desc'} + )); + + // Prints: + // [ + // { + // name: 'HQ', + // distance: 0, + // coordinates: [ 3.910904824733734, 43.607392252329916 ] + // }, + // { + // name: 'other HQ', + // distance: 1367.8521, + // coordinates: [ 3.8971075415611267, 43.600221526170145 ] + // } + // ] + console.log(await kuzzle.ms.georadiusbymember( + 'geofoo', + 'HQ', + 1500, + 'm', + {withcoord: true, withdist: true, sort: 'asc'} + )); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/georadiusbymember/snippets/georadiusbymember.test.yml b/doc/6/controllers/ms/georadiusbymember/snippets/georadiusbymember.test.yml new file mode 100644 index 000000000..a86177ce7 --- /dev/null +++ b/doc/6/controllers/ms/georadiusbymember/snippets/georadiusbymember.test.yml @@ -0,0 +1,18 @@ +name: ms#georadiusbymember +description: Returns the members of a given key inside a radius centered around a key's member +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { name: '(other |)HQ' }, { name: '(other |)HQ' } ]" + - "\\[ { name: 'other HQ', distance: 1367.8521 }," + - " { name: 'HQ', distance: 0 } ]" + - "\\[ { name: 'HQ'," + - " distance: 0," + - " coordinates: \\[ 3.910904824733734, 43.607392252329916 ] }," + - " { name: 'other HQ'," + - " distance: 1367.8521," + - " coordinates: \\[ 3.8971075415611267, 43.600221526170145 ] } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/get/index.md b/doc/6/controllers/ms/get/index.md new file mode 100644 index 000000000..c128a9317 --- /dev/null +++ b/doc/6/controllers/ms/get/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: get +--- + +# get + +Gets the value of a key. + +[[_Redis documentation_]](https://redis.io/commands/get) + +## Arguments + +```js +get(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the key's value. + +## Usage + +<<< ./snippets/get.js diff --git a/doc/6/controllers/ms/get/snippets/get.js b/doc/6/controllers/ms/get/snippets/get.js new file mode 100644 index 000000000..a96b3fd23 --- /dev/null +++ b/doc/6/controllers/ms/get/snippets/get.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + + // Prints: 'bar' + console.log(await kuzzle.ms.get('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/get/snippets/get.test.yml b/doc/6/controllers/ms/get/snippets/get.test.yml new file mode 100644 index 000000000..ede9c73c5 --- /dev/null +++ b/doc/6/controllers/ms/get/snippets/get.test.yml @@ -0,0 +1,9 @@ +name: ms#get +description: Gets the value of a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: bar +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/getbit/index.md b/doc/6/controllers/ms/getbit/index.md new file mode 100644 index 000000000..7a2da9a1d --- /dev/null +++ b/doc/6/controllers/ms/getbit/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: getbit +--- + +# getbit + +Returns the bit value at the provided offset, in the string value stored in a key. + +[[_Redis documentation_]](https://redis.io/commands/getbit) + +## Arguments + +```js +getbit(key, offset, options]) + +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ------------------------ | +| `key` | 
string
| Key | +| `offset` | 
integer
| Bit offset | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the bit at the provided offset (`0` or `1`). + +## Usage + +<<< ./snippets/getbit.js diff --git a/doc/6/controllers/ms/getbit/snippets/getbit.js b/doc/6/controllers/ms/getbit/snippets/getbit.js new file mode 100644 index 000000000..9c3755030 --- /dev/null +++ b/doc/6/controllers/ms/getbit/snippets/getbit.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.set('foo', '\x01'); + + // Prints: 0 + console.log(await kuzzle.ms.getbit('foo', 2)); + + // Prints: 1 + console.log(await kuzzle.ms.getbit('foo', 7)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/getbit/snippets/getbit.test.yml b/doc/6/controllers/ms/getbit/snippets/getbit.test.yml new file mode 100644 index 000000000..ea8ca01aa --- /dev/null +++ b/doc/6/controllers/ms/getbit/snippets/getbit.test.yml @@ -0,0 +1,11 @@ +name: ms#getbit +description: Returns the bit value at the provided offset +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^0$ + - ^1$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/getrange/index.md b/doc/6/controllers/ms/getrange/index.md new file mode 100644 index 000000000..735bbe6e3 --- /dev/null +++ b/doc/6/controllers/ms/getrange/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: getrange +--- + +# getrange + +Returns a substring of a key's value. + +[[_Redis documentation_]](https://redis.io/commands/getrange) + +## Arguments + +```js +getrange(key, start, end, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ------------------------ | +| `key` | 
string
| Key | +| `start` | 
integer
| Range start | +| `end` | 
integer
| Range end | +| `options` | 
object
| Optional query arguments | + +The arguments `start` and `end` can be negative. In that case, the offset is calculated from the end of the string, going backward. For instance, -3 is the third character from the end of the string. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the extracted substring. + +## Usage + +<<< ./snippets/getrange.js diff --git a/doc/6/controllers/ms/getrange/snippets/getrange.js b/doc/6/controllers/ms/getrange/snippets/getrange.js new file mode 100644 index 000000000..653f100c4 --- /dev/null +++ b/doc/6/controllers/ms/getrange/snippets/getrange.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.set('foo', 'foobar'); + + // Prints: 'oba' + console.log(await kuzzle.ms.getrange('foo', 2, 4)); + + // Prints: 'bar' + console.log(await kuzzle.ms.getrange('foo', -3, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/getrange/snippets/getrange.test.yml b/doc/6/controllers/ms/getrange/snippets/getrange.test.yml new file mode 100644 index 000000000..052d7892c --- /dev/null +++ b/doc/6/controllers/ms/getrange/snippets/getrange.test.yml @@ -0,0 +1,11 @@ +name: ms#getrange +description: Returns a substring of a key's value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^oba$ + - ^bar$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/getset/index.md b/doc/6/controllers/ms/getset/index.md new file mode 100644 index 000000000..2db4e8667 --- /dev/null +++ b/doc/6/controllers/ms/getset/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: getset +--- + +# getset + +Sets a new value for a key, and returns its previously stored value. + +[[_Redis documentation_]](https://redis.io/commands/getset) + +## Arguments + +```js +getset(key, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `value` | 
\*
| New key value. | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the previously set value, or `null` if the key didn't exist prior to this operation. + +## Usage + +<<< ./snippets/getset.js diff --git a/doc/6/controllers/ms/getset/snippets/getset.js b/doc/6/controllers/ms/getset/snippets/getset.js new file mode 100644 index 000000000..c94e699ff --- /dev/null +++ b/doc/6/controllers/ms/getset/snippets/getset.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + + // Prints: 'bar' + console.log(await kuzzle.ms.getset('foo', 'qux')); + + // Prints: 'qux' + console.log(await kuzzle.ms.get('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/getset/snippets/getset.test.yml b/doc/6/controllers/ms/getset/snippets/getset.test.yml new file mode 100644 index 000000000..1ae03ae64 --- /dev/null +++ b/doc/6/controllers/ms/getset/snippets/getset.test.yml @@ -0,0 +1,11 @@ +name: ms#getset +description: Sets a new value for a key, and returns its previously stored value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^bar$ + - ^qux$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hdel/index.md b/doc/6/controllers/ms/hdel/index.md new file mode 100644 index 000000000..38c1f83ca --- /dev/null +++ b/doc/6/controllers/ms/hdel/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: hdel +--- + +# hdel + +Removes fields from a hash. + +[[_Redis documentation_]](https://redis.io/commands/hdel) + +## Arguments + +```js +hdel(key, fields, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `key` | 
string
| Hash key | +| `fields` | 
string[]
| Field keys to delete | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of deleted fields. + +## Usage + +<<< ./snippets/hdel.js diff --git a/doc/6/controllers/ms/hdel/snippets/hdel.js b/doc/6/controllers/ms/hdel/snippets/hdel.js new file mode 100644 index 000000000..bf39b7875 --- /dev/null +++ b/doc/6/controllers/ms/hdel/snippets/hdel.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.hset('hashfoo', 'field1', 'val'); + await kuzzle.ms.hset('hashfoo', 'field2', 'val'); + + // Prints: 2 + console.log(await kuzzle.ms.hlen('hashfoo')); + + await kuzzle.ms.hdel('hashfoo', ['field2']); + + // Prints: 1 + console.log(await kuzzle.ms.hlen('hashfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hdel/snippets/hdel.test.yml b/doc/6/controllers/ms/hdel/snippets/hdel.test.yml new file mode 100644 index 000000000..b460b4995 --- /dev/null +++ b/doc/6/controllers/ms/hdel/snippets/hdel.test.yml @@ -0,0 +1,11 @@ +name: ms#hdel +description: Removes fields from a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^2$ + - ^1$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hexists/index.md b/doc/6/controllers/ms/hexists/index.md new file mode 100644 index 000000000..fd1473b39 --- /dev/null +++ b/doc/6/controllers/ms/hexists/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: hexists +--- + +# hexists + +Checks if a field exists in a hash. + +[[_Redis documentation_]](https://redis.io/commands/hexists) + +## Arguments + +```js +hexists(key, field, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Hash key | +| `field` | 
string
| Field name | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean telling whether the checked field exists or not. + +## Usage + +<<< ./snippets/hexists.js diff --git a/doc/6/controllers/ms/hexists/snippets/hexists.js b/doc/6/controllers/ms/hexists/snippets/hexists.js new file mode 100644 index 000000000..f4c7702cd --- /dev/null +++ b/doc/6/controllers/ms/hexists/snippets/hexists.js @@ -0,0 +1,11 @@ +try { + // Prints: false + console.log(await kuzzle.ms.hexists('hashfoo', 'foo')); + + await kuzzle.ms.hset('hashfoo', 'foo', 'bar'); + + // Prints: true + console.log(await kuzzle.ms.hexists('hashfoo', 'foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hexists/snippets/hexists.test.yml b/doc/6/controllers/ms/hexists/snippets/hexists.test.yml new file mode 100644 index 000000000..7d599a8f7 --- /dev/null +++ b/doc/6/controllers/ms/hexists/snippets/hexists.test.yml @@ -0,0 +1,11 @@ +name: ms#hexists +description: Checks if a field exists in a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^false$ + - ^true$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hget/index.md b/doc/6/controllers/ms/hget/index.md new file mode 100644 index 000000000..141228e71 --- /dev/null +++ b/doc/6/controllers/ms/hget/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: hget +--- + +# hget + +Returns the field's value of a hash. + +[[_Redis documentation_]](https://redis.io/commands/hget) + +## Arguments + +```js +hget(key, field, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Hash key | +| `field` | 
string
| Field name | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Returns the field's value. + +## Usage + +<<< ./snippets/hget.js diff --git a/doc/6/controllers/ms/hget/snippets/hget.js b/doc/6/controllers/ms/hget/snippets/hget.js new file mode 100644 index 000000000..1ba799358 --- /dev/null +++ b/doc/6/controllers/ms/hget/snippets/hget.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.hset('hashfoo', 'foo', 'bar'); + + // Prints: 'bar' + console.log(await kuzzle.ms.hget('hashfoo', 'foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hget/snippets/hget.test.yml b/doc/6/controllers/ms/hget/snippets/hget.test.yml new file mode 100644 index 000000000..d020ee976 --- /dev/null +++ b/doc/6/controllers/ms/hget/snippets/hget.test.yml @@ -0,0 +1,9 @@ +name: ms#hget +description: Returns the field's value of a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^bar$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hgetall/index.md b/doc/6/controllers/ms/hgetall/index.md new file mode 100644 index 000000000..99de3f6bd --- /dev/null +++ b/doc/6/controllers/ms/hgetall/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: hgetall +--- + +# hgetall + +Returns all fields and values of a hash. + +[[_Redis documentation_]](https://redis.io/commands/hgetall) + +## Arguments + +```js +hgetall(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Hash key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an object representation of the hash. + +## Usage + +<<< ./snippets/hgetall.js diff --git a/doc/6/controllers/ms/hgetall/snippets/hgetall.js b/doc/6/controllers/ms/hgetall/snippets/hgetall.js new file mode 100644 index 000000000..bf19115fc --- /dev/null +++ b/doc/6/controllers/ms/hgetall/snippets/hgetall.js @@ -0,0 +1,9 @@ +try { + await kuzzle.ms.hset('hashfoo', 'field1', 'val1'); + await kuzzle.ms.hset('hashfoo', 'field2', 'val2'); + + // Prints: { field1: 'val1', field2: 'val2' } + console.log(await kuzzle.ms.hgetall('hashfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hgetall/snippets/hgetall.test.yml b/doc/6/controllers/ms/hgetall/snippets/hgetall.test.yml new file mode 100644 index 000000000..372468a4e --- /dev/null +++ b/doc/6/controllers/ms/hgetall/snippets/hgetall.test.yml @@ -0,0 +1,9 @@ +name: ms#hgetall +description: Returns all fields and values of a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "{ field1: 'val1', field2: 'val2' }" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hincrby/index.md b/doc/6/controllers/ms/hincrby/index.md new file mode 100644 index 000000000..d280835d7 --- /dev/null +++ b/doc/6/controllers/ms/hincrby/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: hincrby +--- + +# hincrby + +Increments the number stored in a hash field by the provided integer value. + +[[_Redis documentation_]](https://redis.io/commands/hincrby) + +## Arguments + +```js +hincrby(key, field, increment, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------ | ------------------------ | +| `key` | 
string
| Hash key | +| `field` | 
string
| Field name | +| `increment` | 
integer
| Increment value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated value of the hash's field. + +## Usage + +<<< ./snippets/hincrby.js diff --git a/doc/6/controllers/ms/hincrby/snippets/hincrby.js b/doc/6/controllers/ms/hincrby/snippets/hincrby.js new file mode 100644 index 000000000..ce4190e4b --- /dev/null +++ b/doc/6/controllers/ms/hincrby/snippets/hincrby.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.hset('hashfoo', 'answer', 100); + + // Prints: 42 + console.log(await kuzzle.ms.hincrby('hashfoo', 'answer', -58)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hincrby/snippets/hincrby.test.yml b/doc/6/controllers/ms/hincrby/snippets/hincrby.test.yml new file mode 100644 index 000000000..3fce3c9b1 --- /dev/null +++ b/doc/6/controllers/ms/hincrby/snippets/hincrby.test.yml @@ -0,0 +1,9 @@ +name: ms#hincrby +description: Increments the number stored in a hash field by the provided integer value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^42$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hincrbyfloat/index.md b/doc/6/controllers/ms/hincrbyfloat/index.md new file mode 100644 index 000000000..f72b5f865 --- /dev/null +++ b/doc/6/controllers/ms/hincrbyfloat/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: hincrbyfloat +--- + +# hincrbyfloat + +Increments the number stored in a hash field by the provided float value. + +[[_Redis documentation_]](https://redis.io/commands/hincrbyfloat) + +## Arguments + +```js +hincrbyfloat(key, field, increment, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ----------------- | ------------------------ | +| `key` | 
string
| Hash key | +| `field` | 
string
| Field name | +| `increment` | 
number
| Increment value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated value of the hash's field. + +## Usage + +<<< ./snippets/hincrbyfloat.js diff --git a/doc/6/controllers/ms/hincrbyfloat/snippets/hincrbyfloat.js b/doc/6/controllers/ms/hincrbyfloat/snippets/hincrbyfloat.js new file mode 100644 index 000000000..d64d30df2 --- /dev/null +++ b/doc/6/controllers/ms/hincrbyfloat/snippets/hincrbyfloat.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.hset('hashfoo', 'almost_pi', 3); + + // Prints: 3.14159 + console.log(await kuzzle.ms.hincrbyfloat('hashfoo', 'almost_pi', 0.14159)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hincrbyfloat/snippets/hincrbyfloat.test.yml b/doc/6/controllers/ms/hincrbyfloat/snippets/hincrbyfloat.test.yml new file mode 100644 index 000000000..9fc6064bc --- /dev/null +++ b/doc/6/controllers/ms/hincrbyfloat/snippets/hincrbyfloat.test.yml @@ -0,0 +1,9 @@ +name: ms#hincrbyfloat +description: Increments the number stored in a hash field by the provided float value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^3.14159$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hkeys/index.md b/doc/6/controllers/ms/hkeys/index.md new file mode 100644 index 000000000..11d1e5063 --- /dev/null +++ b/doc/6/controllers/ms/hkeys/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: hkeys +--- + +# hkeys + +Returns all field names contained in a hash. + +[[_Redis documentation_]](https://redis.io/commands/hkeys) + +## Arguments + +```js +hkeys(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Hash key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an array of hash field names. + +## Usage + +<<< ./snippets/hkeys.js diff --git a/doc/6/controllers/ms/hkeys/snippets/hkeys.js b/doc/6/controllers/ms/hkeys/snippets/hkeys.js new file mode 100644 index 000000000..799a493a4 --- /dev/null +++ b/doc/6/controllers/ms/hkeys/snippets/hkeys.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.hset('hashfoo', 'never', 'foo'); + await kuzzle.ms.hset('hashfoo', 'gonna', 'bar'); + await kuzzle.ms.hset('hashfoo', 'give you up', 'baz'); + + // Prints: ['never', 'gonna', 'give you up'] + console.log(await kuzzle.ms.hkeys('hashfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hkeys/snippets/hkeys.test.yml b/doc/6/controllers/ms/hkeys/snippets/hkeys.test.yml new file mode 100644 index 000000000..91f00c124 --- /dev/null +++ b/doc/6/controllers/ms/hkeys/snippets/hkeys.test.yml @@ -0,0 +1,9 @@ +name: ms#hkeys +description: Returns all field names contained in a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: \[ 'never', 'gonna', 'give you up' ] +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hlen/index.md b/doc/6/controllers/ms/hlen/index.md new file mode 100644 index 000000000..06421b8f7 --- /dev/null +++ b/doc/6/controllers/ms/hlen/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: hlen +--- + +# hlen + +Returns the number of fields contained in a hash. + +[[_Redis documentation_]](https://redis.io/commands/hlen) + +## Arguments + +```js +hlen(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Hash key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of fields stored in a hash. + +## Usage + +<<< ./snippets/hlen.js diff --git a/doc/6/controllers/ms/hlen/snippets/hlen.js b/doc/6/controllers/ms/hlen/snippets/hlen.js new file mode 100644 index 000000000..4f0ff81ac --- /dev/null +++ b/doc/6/controllers/ms/hlen/snippets/hlen.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.hset('hashfoo', 'key1', 'val1'); + await kuzzle.ms.hset('hashfoo', 'key2', 'val2'); + await kuzzle.ms.hset('hashfoo', 'key3', 'val3'); + + // Prints: 3 + console.log(await kuzzle.ms.hlen('hashfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hlen/snippets/hlen.test.yml b/doc/6/controllers/ms/hlen/snippets/hlen.test.yml new file mode 100644 index 000000000..48c6a46b9 --- /dev/null +++ b/doc/6/controllers/ms/hlen/snippets/hlen.test.yml @@ -0,0 +1,9 @@ +name: ms#hlen +description: Returns the number of fields contained in a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^3$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hmget/index.md b/doc/6/controllers/ms/hmget/index.md new file mode 100644 index 000000000..756ad89bd --- /dev/null +++ b/doc/6/controllers/ms/hmget/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: hmget +--- + +# hmget + +Returns the values of the specified hash's fields. + +[[_Redis documentation_]](https://redis.io/commands/hmget) + +## Arguments + +```js +hmget(key, fields, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `key` | 
string
| Hash key | +| `fields` | 
string[]
| Field names | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the list of requested field values, in the same order than in the query. + +## Usage + +<<< ./snippets/hmget.js diff --git a/doc/6/controllers/ms/hmget/snippets/hmget.js b/doc/6/controllers/ms/hmget/snippets/hmget.js new file mode 100644 index 000000000..75883c886 --- /dev/null +++ b/doc/6/controllers/ms/hmget/snippets/hmget.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.hset('hashfoo', 'key1', 'val1'); + await kuzzle.ms.hset('hashfoo', 'key2', 'val2'); + await kuzzle.ms.hset('hashfoo', 'key3', 'val3'); + + // Prints: [ 'val3', 'val1' ] + console.log(await kuzzle.ms.hmget('hashfoo', ['key3', 'key1'])); + +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hmget/snippets/hmget.test.yml b/doc/6/controllers/ms/hmget/snippets/hmget.test.yml new file mode 100644 index 000000000..3a9848b28 --- /dev/null +++ b/doc/6/controllers/ms/hmget/snippets/hmget.test.yml @@ -0,0 +1,9 @@ +name: ms#hmget +description: Returns the values of the specified hash's fields +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: \[ 'val3', 'val1' ] +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hmset/index.md b/doc/6/controllers/ms/hmset/index.md new file mode 100644 index 000000000..757f061b1 --- /dev/null +++ b/doc/6/controllers/ms/hmset/index.md @@ -0,0 +1,50 @@ +--- +code: true +type: page +title: hmset +--- + +# hmset + +Sets multiple fields at once in a hash. + +[[_Redis documentation_]](https://redis.io/commands/hmset) + +## Arguments + +```js +hmset(key, entries, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | -------------------------------- | +| `key` | 
string
| Hash key | +| `entries` | 
object[]
| List of field-value pairs to set | +| `options` | 
object
| Optional query arguments | + +### entries + +The `entries` array lists the fields to set in the hash. Each entry object has the following properties: + +| Properties | Type | Description | +| ---------- | ----------------- | ----------- | +| `field` | 
string
| Field name | +| `value` | 
string
| Field value | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves once the fields have been set. + +## Usage + +<<< ./snippets/hmset.js diff --git a/doc/6/controllers/ms/hmset/snippets/hmset.js b/doc/6/controllers/ms/hmset/snippets/hmset.js new file mode 100644 index 000000000..81ebbdc55 --- /dev/null +++ b/doc/6/controllers/ms/hmset/snippets/hmset.js @@ -0,0 +1,15 @@ +try { + await kuzzle.ms.hmset( + 'hashfoo', + [ + {field: 'key1', value: 'val1'}, + {field: 'key2', value: 'val2'}, + {field: 'key3', value: 'val3'} + ] + ); + + // Prints: { key1: 'val1', key2: 'val2', key3: 'val3' } + console.log(await kuzzle.ms.hgetall('hashfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hmset/snippets/hmset.test.yml b/doc/6/controllers/ms/hmset/snippets/hmset.test.yml new file mode 100644 index 000000000..fbda2f343 --- /dev/null +++ b/doc/6/controllers/ms/hmset/snippets/hmset.test.yml @@ -0,0 +1,9 @@ +name: ms#hmset +description: Sets multiple fields at once in a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: { key1: 'val1', key2: 'val2', key3: 'val3' } +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hscan/index.md b/doc/6/controllers/ms/hscan/index.md new file mode 100644 index 000000000..5112e513e --- /dev/null +++ b/doc/6/controllers/ms/hscan/index.md @@ -0,0 +1,53 @@ +--- +code: true +type: page +title: hscan +--- + +# hscan + +Iterates incrementally over fields contained in a hash, using a cursor. + +An iteration starts when the cursor is set to 0. +To get the next page of results, simply re-send the request with the updated cursor position provided in the result set. + +The scan ends when the cursor returned by the server is 0. + +[[_Redis documentation_]](https://redis.io/commands/hscan) + +## Arguments + +```js +hscan(key, cursor, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ------------------------ | +| `key` | 
string
| Hash key | +| `cursor` | 
integer
| Cursor offset | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `count` | 
integer (10)
| Return an _approximate_ number of items per result set | +| `match` | 
string (\*)
| Return only keys matching the provided pattern | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an object representing a result page, with the following properties: + +| Property | Type | Description | +| -------- | ------------------- | ----------------------------------------------------------------- | +| `cursor` | 
integer
| Cursor offset for the next page, or `0` if at the end of the scan | +| `values` | 
string[]
| List of field-value pairs, alternating field names and values | + +## Usage + +<<< ./snippets/hscan.js diff --git a/doc/6/controllers/ms/hscan/snippets/hscan.js b/doc/6/controllers/ms/hscan/snippets/hscan.js new file mode 100644 index 000000000..7aca23b5e --- /dev/null +++ b/doc/6/controllers/ms/hscan/snippets/hscan.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.hset('hashfoo', 'key1', 'val1'); + await kuzzle.ms.hset('hashfoo', 'key2', 'val2'); + await kuzzle.ms.hset('hashfoo', 'key3', 'val3'); + + // Prints: + // { + // cursor: '0', + // values: [ 'key1', 'val1', 'key2', 'val2', 'key3', 'val3' ] + // } + console.log(await kuzzle.ms.hscan('hashfoo', 0)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hscan/snippets/hscan.test.yml b/doc/6/controllers/ms/hscan/snippets/hscan.test.yml new file mode 100644 index 000000000..ac0824180 --- /dev/null +++ b/doc/6/controllers/ms/hscan/snippets/hscan.test.yml @@ -0,0 +1,11 @@ +name: ms#hscan +description: Iterates incrementally over fields contained in a hash, using a cursor +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "{ cursor: '0'," + - "values: \\[ 'key1', 'val1', 'key2', 'val2', 'key3', 'val3' ] }" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hset/index.md b/doc/6/controllers/ms/hset/index.md new file mode 100644 index 000000000..d45888150 --- /dev/null +++ b/doc/6/controllers/ms/hset/index.md @@ -0,0 +1,46 @@ +--- +code: true +type: page +title: hset +--- + +# hset + +Sets a field and its value in a hash. + +If the key does not exist, a new key holding a hash is created. + +If the field already exists, its value is overwritten. + +[[_Redis documentation_]](https://redis.io/commands/hset) + +## Arguments + +```js +hset(key, field, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Hash key | +| `field` | 
string
| Field name | +| `value` | 
string
| Field value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves once the field has been set. + +## Usage + +<<< ./snippets/hset.js diff --git a/doc/6/controllers/ms/hset/snippets/hset.js b/doc/6/controllers/ms/hset/snippets/hset.js new file mode 100644 index 000000000..f5416da3f --- /dev/null +++ b/doc/6/controllers/ms/hset/snippets/hset.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.hset('hashfoo', 'foo', 'bar'); + + // Prints: { foo: 'bar' } + console.log(await kuzzle.ms.hgetall('hashfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hset/snippets/hset.test.yml b/doc/6/controllers/ms/hset/snippets/hset.test.yml new file mode 100644 index 000000000..f8f074f45 --- /dev/null +++ b/doc/6/controllers/ms/hset/snippets/hset.test.yml @@ -0,0 +1,9 @@ +name: ms#hset +description: Sets a field and its value in a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "{ foo: 'bar' }" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hsetnx/index.md b/doc/6/controllers/ms/hsetnx/index.md new file mode 100644 index 000000000..f49525e41 --- /dev/null +++ b/doc/6/controllers/ms/hsetnx/index.md @@ -0,0 +1,38 @@ +--- +code: true +type: page +title: hsetnx +--- + +# hsetnx + +Sets a field and its value in a hash, only if the field does not already exist. + +[[_Redis documentation_]](https://redis.io/commands/hsetnx) + +## Arguments + +```js +hsetnx(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +## Usage + +<<< ./snippets/hsetnx.js diff --git a/doc/6/controllers/ms/hsetnx/snippets/hsetnx.js b/doc/6/controllers/ms/hsetnx/snippets/hsetnx.js new file mode 100644 index 000000000..3d35c494a --- /dev/null +++ b/doc/6/controllers/ms/hsetnx/snippets/hsetnx.js @@ -0,0 +1,13 @@ +try { + // Prints: true + console.log(await kuzzle.ms.hsetnx('hashfoo', 'foo', 'bar')); + + // Prints: false + console.log(await kuzzle.ms.hsetnx('hashfoo', 'foo', 'qux')); + + // Prints: bar + console.log(await kuzzle.ms.hget('hashfoo', 'foo')); + +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hsetnx/snippets/hsetnx.test.yml b/doc/6/controllers/ms/hsetnx/snippets/hsetnx.test.yml new file mode 100644 index 000000000..7742ae0c6 --- /dev/null +++ b/doc/6/controllers/ms/hsetnx/snippets/hsetnx.test.yml @@ -0,0 +1,12 @@ +name: ms#hsetnx +description: Sets a field and its value in a hash, only if the field does not already exist +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^true$ + - ^false$ + - ^bar$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hstrlen/index.md b/doc/6/controllers/ms/hstrlen/index.md new file mode 100644 index 000000000..23f2ce826 --- /dev/null +++ b/doc/6/controllers/ms/hstrlen/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: hstrlen +--- + +# hstrlen + +Returns the string length of a field's value in a hash. + +[[_Redis documentation_]](https://redis.io/commands/hstrlen) + +## Arguments + +```js +hstrlen(key, field, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `field` | 
string
| Field name | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the field value length. + +## Usage + +<<< ./snippets/hstrlen.js diff --git a/doc/6/controllers/ms/hstrlen/snippets/hstrlen.js b/doc/6/controllers/ms/hstrlen/snippets/hstrlen.js new file mode 100644 index 000000000..ff3e5e7bd --- /dev/null +++ b/doc/6/controllers/ms/hstrlen/snippets/hstrlen.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.hset('hashfoo', 'foo', 'bar'); + + // Prints: 3 + console.log(await kuzzle.ms.hstrlen('hashfoo', 'foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hstrlen/snippets/hstrlen.test.yml b/doc/6/controllers/ms/hstrlen/snippets/hstrlen.test.yml new file mode 100644 index 000000000..ef71bdf52 --- /dev/null +++ b/doc/6/controllers/ms/hstrlen/snippets/hstrlen.test.yml @@ -0,0 +1,9 @@ +name: ms#hstrlen +description: Returns the string length of a field's value in a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^3$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/hvals/index.md b/doc/6/controllers/ms/hvals/index.md new file mode 100644 index 000000000..7efa03a56 --- /dev/null +++ b/doc/6/controllers/ms/hvals/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: hvals +--- + +# hvals + +Returns all values contained in a hash. + +[[_Redis documentation_]](https://redis.io/commands/hvals) + +## Arguments + +```js +hvals(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the list of hash's field values. + +## Usage + +<<< ./snippets/hvals.js diff --git a/doc/6/controllers/ms/hvals/snippets/hvals.js b/doc/6/controllers/ms/hvals/snippets/hvals.js new file mode 100644 index 000000000..4d3159555 --- /dev/null +++ b/doc/6/controllers/ms/hvals/snippets/hvals.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.hset('hashfoo', 'key1', 'val1'); + await kuzzle.ms.hset('hashfoo', 'key2', 'val2'); + await kuzzle.ms.hset('hashfoo', 'key3', 'val3'); + + // Prints: [ 'val1', 'val2', 'val3' ] + console.log(await kuzzle.ms.hvals('hashfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/hvals/snippets/hvals.test.yml b/doc/6/controllers/ms/hvals/snippets/hvals.test.yml new file mode 100644 index 000000000..efe75d69d --- /dev/null +++ b/doc/6/controllers/ms/hvals/snippets/hvals.test.yml @@ -0,0 +1,9 @@ +name: ms#hvals +description: Returns all values contained in a hash +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'val1', 'val2', 'val3' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/incr/index.md b/doc/6/controllers/ms/incr/index.md new file mode 100644 index 000000000..81ac08daa --- /dev/null +++ b/doc/6/controllers/ms/incr/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: incr +--- + +# incr + +Increments the number stored at `key` by 1. If the key does not exist, it is set to 0 before performing the operation. + +[[_Redis documentation_]](https://redis.io/commands/incr) + +## Arguments + +```js +incr(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the incremented key value. + +## Usage + +<<< ./snippets/incr.js diff --git a/doc/6/controllers/ms/incr/snippets/incr.js b/doc/6/controllers/ms/incr/snippets/incr.js new file mode 100644 index 000000000..833c8b1b3 --- /dev/null +++ b/doc/6/controllers/ms/incr/snippets/incr.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('foo', 41); + + // Prints: 42 + console.log(await kuzzle.ms.incr('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/incr/snippets/incr.test.yml b/doc/6/controllers/ms/incr/snippets/incr.test.yml new file mode 100644 index 000000000..8eb956a22 --- /dev/null +++ b/doc/6/controllers/ms/incr/snippets/incr.test.yml @@ -0,0 +1,9 @@ +name: ms#incr +description: Increments the number stored at key by 1 +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^42$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/incrby/index.md b/doc/6/controllers/ms/incrby/index.md new file mode 100644 index 000000000..fc17f6264 --- /dev/null +++ b/doc/6/controllers/ms/incrby/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: incrby +--- + +# incrby + +Increments the number stored at `key` by the provided integer value. If the key does not exist, it is set to 0 before performing the operation. + +[[_Redis documentation_]](https://redis.io/commands/incrby) + +## Arguments + +```js +incrby(key, increment, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------ | ------------------------ | +| `key` | 
string
| Key | +| `increment` | 
integer
| Increment value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the incremented key value. + +## Usage + +<<< ./snippets/incrby.js diff --git a/doc/6/controllers/ms/incrby/snippets/incrby.js b/doc/6/controllers/ms/incrby/snippets/incrby.js new file mode 100644 index 000000000..9fbf7e5a0 --- /dev/null +++ b/doc/6/controllers/ms/incrby/snippets/incrby.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('foo', 100); + + // Prints: 42 + console.log(await kuzzle.ms.incrby('foo', -58)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/incrby/snippets/incrby.test.yml b/doc/6/controllers/ms/incrby/snippets/incrby.test.yml new file mode 100644 index 000000000..66b93f139 --- /dev/null +++ b/doc/6/controllers/ms/incrby/snippets/incrby.test.yml @@ -0,0 +1,9 @@ +name: ms#incrby +description: Increments the number stored at `key` by the provided integer value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^42$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/incrbyfloat/index.md b/doc/6/controllers/ms/incrbyfloat/index.md new file mode 100644 index 000000000..fca7286f8 --- /dev/null +++ b/doc/6/controllers/ms/incrbyfloat/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: incrbyfloat +--- + +# incrbyfloat + +Increments the number stored at `key` by the provided float value. If the key does not exist, it is set to 0 before performing the operation. + +[[_Redis documentation_]](https://redis.io/commands/incrbyfloat) + +## Arguments + +```js +incrbyfloat(key, increment, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `increment` | 
number
| Increment value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the incremented value. + +## Usage + +<<< ./snippets/incrbyfloat.js diff --git a/doc/6/controllers/ms/incrbyfloat/snippets/incrbyfloat.js b/doc/6/controllers/ms/incrbyfloat/snippets/incrbyfloat.js new file mode 100644 index 000000000..c518c2614 --- /dev/null +++ b/doc/6/controllers/ms/incrbyfloat/snippets/incrbyfloat.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('almost pi', 3); + + // Prints: 3.14159 + console.log(await kuzzle.ms.incrbyfloat('almost pi', 0.14159)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/incrbyfloat/snippets/incrbyfloat.test.yml b/doc/6/controllers/ms/incrbyfloat/snippets/incrbyfloat.test.yml new file mode 100644 index 000000000..f9695c2f5 --- /dev/null +++ b/doc/6/controllers/ms/incrbyfloat/snippets/incrbyfloat.test.yml @@ -0,0 +1,9 @@ +name: ms#incrbyfloat +description: Increments the number stored at key by the provided float value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^3.14159$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/index.md b/doc/6/controllers/ms/index.md new file mode 100644 index 000000000..02d0feef7 --- /dev/null +++ b/doc/6/controllers/ms/index.md @@ -0,0 +1,6 @@ +--- +code: true +type: branch +title: ms +description: memory storage controller documentation +--- diff --git a/doc/6/controllers/ms/keys/index.md b/doc/6/controllers/ms/keys/index.md new file mode 100644 index 000000000..53433d409 --- /dev/null +++ b/doc/6/controllers/ms/keys/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: keys +--- + +# keys + +Returns all keys matching the provided pattern. + +[[_Redis documentation_]](https://redis.io/commands/keys) + +## Arguments + +```js +keys(pattern, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ----------------- | +| `pattern` | 
string
| Match pattern | +| | `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an array of key identifiers. + +## Usage + +<<< ./snippets/keys.js diff --git a/doc/6/controllers/ms/keys/snippets/keys.js b/doc/6/controllers/ms/keys/snippets/keys.js new file mode 100644 index 000000000..bcf66a5d7 --- /dev/null +++ b/doc/6/controllers/ms/keys/snippets/keys.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + await kuzzle.ms.set('Suddenly', 'Bananas'); + await kuzzle.ms.set('Hello', 'World'); + + // Prints: [ 'foo', 'Hello' ] + console.log(await kuzzle.ms.keys('*o')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/keys/snippets/keys.test.yml b/doc/6/controllers/ms/keys/snippets/keys.test.yml new file mode 100644 index 000000000..ec079ebad --- /dev/null +++ b/doc/6/controllers/ms/keys/snippets/keys.test.yml @@ -0,0 +1,9 @@ +name: ms#keys +description: Returns all keys matching the provided pattern +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ '(Hello|foo)', '(Hello|foo)' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/lindex/index.md b/doc/6/controllers/ms/lindex/index.md new file mode 100644 index 000000000..2841425a3 --- /dev/null +++ b/doc/6/controllers/ms/lindex/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: lindex +--- + +# lindex + +Returns the element at the provided index in a list. + +[[_Redis documentation_]](https://redis.io/commands/lindex) + +## Arguments + +```js +lindex(key, index, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ------------------------ | +| `key` | 
string
| List key | +| `index` | 
integer
| List index | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the stored value at the provided list index. + +## Usage + +<<< ./snippets/lindex.js diff --git a/doc/6/controllers/ms/lindex/snippets/lindex.js b/doc/6/controllers/ms/lindex/snippets/lindex.js new file mode 100644 index 000000000..5effdd332 --- /dev/null +++ b/doc/6/controllers/ms/lindex/snippets/lindex.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'baz']); + + // Prints: bar + console.log(await kuzzle.ms.lindex('listfoo', 1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/lindex/snippets/lindex.test.yml b/doc/6/controllers/ms/lindex/snippets/lindex.test.yml new file mode 100644 index 000000000..8abf7ad84 --- /dev/null +++ b/doc/6/controllers/ms/lindex/snippets/lindex.test.yml @@ -0,0 +1,9 @@ +name: ms#lindex +description: Returns the element at the provided index in a list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^bar$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/linsert/index.md b/doc/6/controllers/ms/linsert/index.md new file mode 100644 index 000000000..5bba89e36 --- /dev/null +++ b/doc/6/controllers/ms/linsert/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: linsert +--- + +# linsert + +Inserts a value in a list, either before or after a pivot value. + +[[_Redis documentation_]](https://redis.io/commands/linsert) + +## Arguments + +```js +linsert(key, position, pivot, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| ---------- | ----------------- | --------------------------------------------------------------------- | +| `key` | 
string
| List key | +| `position` | 
string
| Position relative to the pivot.
Allowed values: `before`, `after` | +| `pivot` | 
string
| Existing list value to use as a pivot | +| `value` | 
string
| Value to insert | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated length of the list. + +## Usage + +<<< ./snippets/linsert.js diff --git a/doc/6/controllers/ms/linsert/snippets/linsert.js b/doc/6/controllers/ms/linsert/snippets/linsert.js new file mode 100644 index 000000000..1c73644d8 --- /dev/null +++ b/doc/6/controllers/ms/linsert/snippets/linsert.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'baz']); + + await kuzzle.ms.linsert('listfoo', 'before', 'bar', 'qux'); + + // Prints: [ 'foo', 'qux', 'bar', 'baz' ] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/linsert/snippets/linsert.test.yml b/doc/6/controllers/ms/linsert/snippets/linsert.test.yml new file mode 100644 index 000000000..ffa21f82c --- /dev/null +++ b/doc/6/controllers/ms/linsert/snippets/linsert.test.yml @@ -0,0 +1,9 @@ +name: ms#linsert +description: Inserts a value in a list, either before or after a pivot value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'foo', 'qux', 'bar', 'baz' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/llen/index.md b/doc/6/controllers/ms/llen/index.md new file mode 100644 index 000000000..be28549f7 --- /dev/null +++ b/doc/6/controllers/ms/llen/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: llen +--- + +# llen + +Returns the length of a list. + +[[_Redis documentation_]](https://redis.io/commands/llen) + +## Arguments + +```js +llen(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| List key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the length of the list. + +## Usage + +<<< ./snippets/llen.js diff --git a/doc/6/controllers/ms/llen/snippets/llen.js b/doc/6/controllers/ms/llen/snippets/llen.js new file mode 100644 index 000000000..7ff06fa91 --- /dev/null +++ b/doc/6/controllers/ms/llen/snippets/llen.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'baz']); + + // Prints: 3 + console.log(await kuzzle.ms.llen('listfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/llen/snippets/llen.test.yml b/doc/6/controllers/ms/llen/snippets/llen.test.yml new file mode 100644 index 000000000..65112883a --- /dev/null +++ b/doc/6/controllers/ms/llen/snippets/llen.test.yml @@ -0,0 +1,9 @@ +name: ms#llen +description: Returns the length of a list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^3$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/lpop/index.md b/doc/6/controllers/ms/lpop/index.md new file mode 100644 index 000000000..dc2533a33 --- /dev/null +++ b/doc/6/controllers/ms/lpop/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: lpop +--- + +# lpop + +Removes and returns the first element of a list. + +[[_Redis documentation_]](https://redis.io/commands/lpop) + +## Arguments + +```js +lpop(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| List key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the value extracted from the list. + +## Usage + +<<< ./snippets/lpop.js diff --git a/doc/6/controllers/ms/lpop/snippets/lpop.js b/doc/6/controllers/ms/lpop/snippets/lpop.js new file mode 100644 index 000000000..1e411615d --- /dev/null +++ b/doc/6/controllers/ms/lpop/snippets/lpop.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'baz']); + + // Prints: foo + console.log(await kuzzle.ms.lpop('listfoo')); + + // Prints: [ 'bar', 'baz' ] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/lpop/snippets/lpop.test.yml b/doc/6/controllers/ms/lpop/snippets/lpop.test.yml new file mode 100644 index 000000000..c812c4378 --- /dev/null +++ b/doc/6/controllers/ms/lpop/snippets/lpop.test.yml @@ -0,0 +1,11 @@ +name: ms#lpop +description: Removes and returns the first element of a list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^foo$ + - "\\[ 'bar', 'baz' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/lpush/index.md b/doc/6/controllers/ms/lpush/index.md new file mode 100644 index 000000000..abe0e6fc1 --- /dev/null +++ b/doc/6/controllers/ms/lpush/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: lpush +--- + +# lpush + +Prepends the specified values to a list. + +If the key does not exist, it is created holding an empty list before performing the operation. + +[[_Redis documentation_]](https://redis.io/commands/lpush) + +## Arguments + +```js +lpush(key, values, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `key` | 
string
| List key | +| `values` | 
string[]
| Values to append | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated length of the list. + +## Usage + +<<< ./snippets/lpush.js diff --git a/doc/6/controllers/ms/lpush/snippets/lpush.js b/doc/6/controllers/ms/lpush/snippets/lpush.js new file mode 100644 index 000000000..e8a8534f2 --- /dev/null +++ b/doc/6/controllers/ms/lpush/snippets/lpush.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.rpush('listfoo', ['foobar']); + + // Prints: 3 + console.log(await kuzzle.ms.lpush('listfoo', ['World', 'Hello'])); + + // Prints: [ 'Hello', 'World', 'foobar' ] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/lpush/snippets/lpush.test.yml b/doc/6/controllers/ms/lpush/snippets/lpush.test.yml new file mode 100644 index 000000000..0d671ed18 --- /dev/null +++ b/doc/6/controllers/ms/lpush/snippets/lpush.test.yml @@ -0,0 +1,11 @@ +name: ms#lpush +description: Prepends the specified values to a list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^3$ + - "\\[ 'Hello', 'World', 'foobar' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/lpushx/index.md b/doc/6/controllers/ms/lpushx/index.md new file mode 100644 index 000000000..37606192d --- /dev/null +++ b/doc/6/controllers/ms/lpushx/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: lpushx +--- + +# lpushx + +Prepends the specified value to a list, only if the key already exists and if it holds a list. + +[[_Redis documentation_]](https://redis.io/commands/lpushx) + +## Arguments + +```js +lpushx(key, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Existing list key | +| `value` | 
string
| Value to append | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated list length. + +## Usage + +<<< ./snippets/lpushx.js diff --git a/doc/6/controllers/ms/lpushx/snippets/lpushx.js b/doc/6/controllers/ms/lpushx/snippets/lpushx.js new file mode 100644 index 000000000..0adf26657 --- /dev/null +++ b/doc/6/controllers/ms/lpushx/snippets/lpushx.js @@ -0,0 +1,17 @@ +try { + // Prints: 0 + console.log(await kuzzle.ms.lpushx('listfoo', 'foo')); + + // Prints: [] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); + + await kuzzle.ms.lpush('listfoo', ['bar']); + + // Prints: 2 + console.log(await kuzzle.ms.lpushx('listfoo', 'foo')); + + // Prints: [ 'foo', 'bar' ] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/lpushx/snippets/lpushx.test.yml b/doc/6/controllers/ms/lpushx/snippets/lpushx.test.yml new file mode 100644 index 000000000..029a61412 --- /dev/null +++ b/doc/6/controllers/ms/lpushx/snippets/lpushx.test.yml @@ -0,0 +1,13 @@ +name: ms#lpushx +description: Prepends the specified value to an existing list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^0$ + - "\\[]" + - ^2$ + - "\\[ 'foo', 'bar' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/lrange/index.md b/doc/6/controllers/ms/lrange/index.md new file mode 100644 index 000000000..1997c0299 --- /dev/null +++ b/doc/6/controllers/ms/lrange/index.md @@ -0,0 +1,46 @@ +--- +code: true +type: page +title: lrange +--- + +# lrange + +Returns the list elements between the `start` and `stop` positions. + +Offsets start at `0`, and the range is inclusive. + +[[_Redis documentation_]](https://redis.io/commands/lrange) + +## Arguments + +```js +lrange(key, start, stop, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | -------------------------- | +| `key` | 
string
| List key | +| `start` | 
integer
| Starting index (inclusive) | +| `stop` | 
integer
| Ending index (inclusive) | +| `options` | 
object
| Optional query arguments | + +The `start` and `stop` arguments can be negative. In that case, the offset is calculated from the end of the list, going backward. For instance, -3 is the third element from the end of the list. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an array of list elements. + +## Usage + +<<< ./snippets/lrange.js diff --git a/doc/6/controllers/ms/lrange/snippets/lrange.js b/doc/6/controllers/ms/lrange/snippets/lrange.js new file mode 100644 index 000000000..f7b57bfe5 --- /dev/null +++ b/doc/6/controllers/ms/lrange/snippets/lrange.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.rpush('listfoo', ['a', 'b', 'c', 'd', 'e', 'f']); + + // Prints: [ 'b', 'c', 'd' ] + console.log(await kuzzle.ms.lrange('listfoo', 1, 3)); + + // Prints: [ d', 'e' ] + console.log(await kuzzle.ms.lrange('listfoo', 3, -2)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/lrange/snippets/lrange.test.yml b/doc/6/controllers/ms/lrange/snippets/lrange.test.yml new file mode 100644 index 000000000..0c47e421a --- /dev/null +++ b/doc/6/controllers/ms/lrange/snippets/lrange.test.yml @@ -0,0 +1,11 @@ +name: ms#lrange +description: Returns the list elements between the start and stop positions +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ 'b', 'c', 'd' ]" + - "\\[ 'd', 'e' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/lrem/index.md b/doc/6/controllers/ms/lrem/index.md new file mode 100644 index 000000000..87f7c3bc1 --- /dev/null +++ b/doc/6/controllers/ms/lrem/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: lrem +--- + +# lrem + +Removes the first occurences of an element from a list. + +[[_Redis documentation_]](https://redis.io/commands/lrem) + +## Arguments + +```js +lrem(key, count, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ---------------------------------------------- | +| `key` | 
string
| List key | +| `count` | 
integer
| Number of the first found occurences to remove | +| `value` | 
string
| Value to remove | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of removed elements. + +## Usage + +<<< ./snippets/lrem.js diff --git a/doc/6/controllers/ms/lrem/snippets/lrem.js b/doc/6/controllers/ms/lrem/snippets/lrem.js new file mode 100644 index 000000000..0775173d5 --- /dev/null +++ b/doc/6/controllers/ms/lrem/snippets/lrem.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'foo', 'baz', 'foo']); + + // Prints: 2 + console.log(await kuzzle.ms.lrem('listfoo', 2, 'foo')); + + // Prints: [ 'bar', 'baz', 'foo' ] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/lrem/snippets/lrem.test.yml b/doc/6/controllers/ms/lrem/snippets/lrem.test.yml new file mode 100644 index 000000000..dd43df76d --- /dev/null +++ b/doc/6/controllers/ms/lrem/snippets/lrem.test.yml @@ -0,0 +1,11 @@ +name: ms#lrem +description: Removes the first occurences of an element from a list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^2$ + - "\\[ 'bar', 'baz', 'foo' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/lset/index.md b/doc/6/controllers/ms/lset/index.md new file mode 100644 index 000000000..004a8281c --- /dev/null +++ b/doc/6/controllers/ms/lset/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: lset +--- + +# lset + +Sets the list element at `index` with the provided value. + +[[_Redis documentation_]](https://redis.io/commands/lset) + +## Arguments + +```js +lset(key, index, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ----------------------------------------------------------------------------------------------- | +| `key` | 
string
| List key | +| `index` | 
integer
| Index of the list (lists are 0-indexed). If negative, it goes backward from the end of the list | +| `value` | 
string
| Value to set | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves once the new value is set. + +## Usage + +<<< ./snippets/lset.js diff --git a/doc/6/controllers/ms/lset/snippets/lset.js b/doc/6/controllers/ms/lset/snippets/lset.js new file mode 100644 index 000000000..1d8e24dad --- /dev/null +++ b/doc/6/controllers/ms/lset/snippets/lset.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.rpush('listfoo', ['qux', 'bar', 'baz']); + + await kuzzle.ms.lset('listfoo', 0, 'foo'); + + // Prints: [ 'foo', 'bar', 'baz' ] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/lset/snippets/lset.test.yml b/doc/6/controllers/ms/lset/snippets/lset.test.yml new file mode 100644 index 000000000..8102ca92f --- /dev/null +++ b/doc/6/controllers/ms/lset/snippets/lset.test.yml @@ -0,0 +1,9 @@ +name: ms#lset +description: Sets the list element at index with the provided value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'foo', 'bar', 'baz' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/ltrim/index.md b/doc/6/controllers/ms/ltrim/index.md new file mode 100644 index 000000000..daee7ddb7 --- /dev/null +++ b/doc/6/controllers/ms/ltrim/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: ltrim +--- + +# ltrim + +Trims an existing list so that it will contain only the specified range of elements specified. + +[[_Redis documentation_]](https://redis.io/commands/ltrim) + +## Arguments + +```js +ltrim(key, start, stop, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | -------------------------- | +| `key` | 
string
| List key | +| `start` | 
integer
| Starting index (inclusive) | +| `stop` | 
integer
| Ending index (inclusive) | +| `options` | 
object
| Optional query arguments | + +The `start` and `stop` arguments can be negative. In that case, the offset is calculated from the end of the list, going backward. For instance, -3 is the third element from the end of the list. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves once the operation is finished. + +## Usage + +<<< ./snippets/ltrim.js diff --git a/doc/6/controllers/ms/ltrim/snippets/ltrim.js b/doc/6/controllers/ms/ltrim/snippets/ltrim.js new file mode 100644 index 000000000..70ecb7d93 --- /dev/null +++ b/doc/6/controllers/ms/ltrim/snippets/ltrim.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.rpush('listfoo', ['a', 'b', 'c', 'd', 'e', 'f']); + + await kuzzle.ms.ltrim('listfoo', 3, -2); + + // Prints [ 'd', 'e' ] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/ltrim/snippets/ltrim.test.yml b/doc/6/controllers/ms/ltrim/snippets/ltrim.test.yml new file mode 100644 index 000000000..96629d68e --- /dev/null +++ b/doc/6/controllers/ms/ltrim/snippets/ltrim.test.yml @@ -0,0 +1,9 @@ +name: ms#ltrim +description: Trims an existing list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'd', 'e' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/mget/index.md b/doc/6/controllers/ms/mget/index.md new file mode 100644 index 000000000..99488fafa --- /dev/null +++ b/doc/6/controllers/ms/mget/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: mget +--- + +# mget + +Returns the values of the provided keys. + +[[_Redis documentation_]](https://redis.io/commands/mget) + +## Arguments + +```js +mget(keys, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `keys` | 
string[]
| List of keys to get | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the list of corresponding key values, in the same order than the one provided in the query. + +## Usage + +<<< ./snippets/mget.js diff --git a/doc/6/controllers/ms/mget/snippets/mget.js b/doc/6/controllers/ms/mget/snippets/mget.js new file mode 100644 index 000000000..46bfef49f --- /dev/null +++ b/doc/6/controllers/ms/mget/snippets/mget.js @@ -0,0 +1,9 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + await kuzzle.ms.set('hello', 'world'); + + // Prints: [ 'world', 'bar' ] + console.log(await kuzzle.ms.mget(['hello', 'foo'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/mget/snippets/mget.test.yml b/doc/6/controllers/ms/mget/snippets/mget.test.yml new file mode 100644 index 000000000..23195d61f --- /dev/null +++ b/doc/6/controllers/ms/mget/snippets/mget.test.yml @@ -0,0 +1,9 @@ +name: ms#mget +description: Returns the values of the provided keys +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'world', 'bar' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/mset/index.md b/doc/6/controllers/ms/mset/index.md new file mode 100644 index 000000000..ddd5cf64f --- /dev/null +++ b/doc/6/controllers/ms/mset/index.md @@ -0,0 +1,49 @@ +--- +code: true +type: page +title: mset +--- + +# mset + +Sets the provided keys to their respective values. If a key does not exist, it is created. Otherwise, the key's value is overwritten. + +[[_Redis documentation_]](https://redis.io/commands/mset) + +## Arguments + +```js +mset(entries, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------------ | +| `entries` | 
object[]
| List of key-value pairs to set | +| `options` | 
object
| Optional query arguments | + +### entries + +The `entries` argument is an array of objects. Each object is a key-value pair, defined with the following properties: + +| Property | Type | Description | +| -------- | ----------------- | ----------- | +| `key` | 
string
| Key | +| `value` | 
\*
| Value | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves successfully once the keys are set. + +## Usage + +<<< ./snippets/mset.js diff --git a/doc/6/controllers/ms/mset/snippets/mset.js b/doc/6/controllers/ms/mset/snippets/mset.js new file mode 100644 index 000000000..579c5a54f --- /dev/null +++ b/doc/6/controllers/ms/mset/snippets/mset.js @@ -0,0 +1,15 @@ +try { + // Prints: 0 + console.log(await kuzzle.ms.exists(['key1', 'key2', 'key3'])); + + await kuzzle.ms.mset([ + { key: 'key1', value: 'val1' }, + { key: 'key2', value: 'val2' }, + { key: 'key3', value: 'val3' } + ]); + + // Prints: 3 + console.log(await kuzzle.ms.exists(['key1', 'key2', 'key3'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/mset/snippets/mset.test.yml b/doc/6/controllers/ms/mset/snippets/mset.test.yml new file mode 100644 index 000000000..8effcbefc --- /dev/null +++ b/doc/6/controllers/ms/mset/snippets/mset.test.yml @@ -0,0 +1,11 @@ +name: ms#mset +description: Sets the provided keys to their respective values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^0$ + - ^3$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/msetnx/index.md b/doc/6/controllers/ms/msetnx/index.md new file mode 100644 index 000000000..64cc99b2a --- /dev/null +++ b/doc/6/controllers/ms/msetnx/index.md @@ -0,0 +1,49 @@ +--- +code: true +type: page +title: msetnx +--- + +# msetnx + +Sets the provided keys to their respective values, only if they do not exist. If a key exists, then the whole operation is aborted and no key is set. + +[[_Redis documentation_]](https://redis.io/commands/msetnx) + +## Arguments + +```js +msetnx(entries, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------------ | +| `entries` | 
object[]
| List of key-value pairs to set | +| `options` | 
object
| Optional query arguments | + +### entries + +The `entries` argument is an array of objects. Each object is a key-value pair, defined with the following properties: + +| Property | Type | Description | +| -------- | ----------------- | ----------- | +| `key` | 
string
| Key | +| `value` | 
\*
| Value | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean telling whether the keys have been set or not. + +## Usage + +<<< ./snippets/msetnx.js diff --git a/doc/6/controllers/ms/msetnx/snippets/msetnx.js b/doc/6/controllers/ms/msetnx/snippets/msetnx.js new file mode 100644 index 000000000..70a76ee8c --- /dev/null +++ b/doc/6/controllers/ms/msetnx/snippets/msetnx.js @@ -0,0 +1,19 @@ +const entries = [ + { key: 'hello', value: 'world' }, + { key: 'foo', value: 'bar' } +]; + +try { + await kuzzle.ms.set('foo', 'bar'); + + // Prints: false + // (the entire operation aborted) + console.log(await kuzzle.ms.msetnx(entries)); + + await kuzzle.ms.del('foo'); + + // Prints: true + console.log(await kuzzle.ms.msetnx(entries)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/msetnx/snippets/msetnx.test.yml b/doc/6/controllers/ms/msetnx/snippets/msetnx.test.yml new file mode 100644 index 000000000..f73ac5b14 --- /dev/null +++ b/doc/6/controllers/ms/msetnx/snippets/msetnx.test.yml @@ -0,0 +1,11 @@ +name: ms#msetnx +description: Sets the provided keys to their respective values, only if they do not exist +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^false$ + - ^true$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/object/index.md b/doc/6/controllers/ms/object/index.md new file mode 100644 index 000000000..9c87e3bcc --- /dev/null +++ b/doc/6/controllers/ms/object/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: object +--- + +# object + +Inspects the low-level properties of a key. + +[[_Redis documentation_]](https://redis.io/commands/object) + +## Arguments + +```js +object(key, subcommand, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ----------------- | ---------------------------------------------------------------------------------- | +| `key` | 
string
| Key | +| `subcommand` | 
string
| Object property to inspect.
Allowed values: `encoding`, `idletime`, `refcount` | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the inspected property value. + +## Usage + +<<< ./snippets/object.js diff --git a/doc/6/controllers/ms/object/snippets/object.js b/doc/6/controllers/ms/object/snippets/object.js new file mode 100644 index 000000000..beef89a13 --- /dev/null +++ b/doc/6/controllers/ms/object/snippets/object.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.sadd('foo', ['bar', 'baz']); + + // Prints: hashtable + console.log(await kuzzle.ms.object('foo', 'encoding')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/object/snippets/object.test.yml b/doc/6/controllers/ms/object/snippets/object.test.yml new file mode 100644 index 000000000..ec96be4b7 --- /dev/null +++ b/doc/6/controllers/ms/object/snippets/object.test.yml @@ -0,0 +1,9 @@ +name: ms#object +description: Inspects the low-level properties of a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^hashtable$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/persist/index.md b/doc/6/controllers/ms/persist/index.md new file mode 100644 index 000000000..19963bcc9 --- /dev/null +++ b/doc/6/controllers/ms/persist/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: persist +--- + +# persist + +Removes the expiration delay or timestamp from a key, making it persistent. + +[[_Redis documentation_]](https://redis.io/commands/persist) + +## Arguments + +```js +persist(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves once the key is persisted. + +## Usage + +<<< ./snippets/persist.js diff --git a/doc/6/controllers/ms/persist/snippets/persist.js b/doc/6/controllers/ms/persist/snippets/persist.js new file mode 100644 index 000000000..aba174638 --- /dev/null +++ b/doc/6/controllers/ms/persist/snippets/persist.js @@ -0,0 +1,13 @@ +try { + await kuzzle.ms.setex('foo', 'bar', 60); + + // Prints: 60 + console.log(await kuzzle.ms.ttl('foo')); + + await kuzzle.ms.persist('foo'); + + // Prints: -1 + console.log(await kuzzle.ms.ttl('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/persist/snippets/persist.test.yml b/doc/6/controllers/ms/persist/snippets/persist.test.yml new file mode 100644 index 000000000..5a3b014a3 --- /dev/null +++ b/doc/6/controllers/ms/persist/snippets/persist.test.yml @@ -0,0 +1,11 @@ +name: ms#persist +description: Removes the expiration delay or timestamp from a key, making it persistent +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^[0-9]+$ + - "-1" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/pexpire/index.md b/doc/6/controllers/ms/pexpire/index.md new file mode 100644 index 000000000..92a540532 --- /dev/null +++ b/doc/6/controllers/ms/pexpire/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: pexpire +--- + +# pexpire + +Sets a timeout (in milliseconds) on a key. After the timeout has expired, the key will automatically be deleted. + +[[_Redis documentation_]](https://redis.io/commands/pexpire) + +## Arguments + +```js +pexpire(key, milliseconds, [options]); +``` + +
+ +| Arguments | Type | Description | +| -------------- | ------------------ | ----------------------------------------------------- | +| `key` | 
string
| Key | +| `milliseconds` | 
integer
| Number of milliseconds after which the key is deleted | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean, telling whether the operation succeeded or not. + +## Usage + +<<< ./snippets/pexpire.js diff --git a/doc/6/controllers/ms/pexpire/snippets/pexpire.js b/doc/6/controllers/ms/pexpire/snippets/pexpire.js new file mode 100644 index 000000000..6cb30e4d7 --- /dev/null +++ b/doc/6/controllers/ms/pexpire/snippets/pexpire.js @@ -0,0 +1,13 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + + // Prints: -1 + console.log(await kuzzle.ms.ttl('foo')); + + await kuzzle.ms.pexpire('foo', 60000); + + // Prints: 60 + console.log(await kuzzle.ms.ttl('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/pexpire/snippets/pexpire.test.yml b/doc/6/controllers/ms/pexpire/snippets/pexpire.test.yml new file mode 100644 index 000000000..caf2552ea --- /dev/null +++ b/doc/6/controllers/ms/pexpire/snippets/pexpire.test.yml @@ -0,0 +1,11 @@ +name: ms#pexpire +description: Sets a timeout (in milliseconds) on a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^-1$ + - ^[0-9]{1,2}$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/pexpireat/index.md b/doc/6/controllers/ms/pexpireat/index.md new file mode 100644 index 000000000..ff31c6941 --- /dev/null +++ b/doc/6/controllers/ms/pexpireat/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: pexpireat +--- + +# pexpireat + +Sets an expiration timestamp (in Epoch-milis) on a key. After the timestamp has been reached, the key will automatically be deleted. + +[[_Redis documentation_]](https://redis.io/commands/pexpireat) + +## Arguments + +```js +pexpireat(key, timestamp, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------ | ----------------------------------------------------------------------------------------------- | +| `key` | 
string
| Key | +| `timestamp` | 
integer
| Expiration timestamp ([Epoch](https://en.wikipedia.org/wiki/Unix_time) format, in milliseconds) | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean telling whether the operation was successful or not. + +## Usage + +<<< ./snippets/pexpireat.js diff --git a/doc/6/controllers/ms/pexpireat/snippets/pexpireat.js b/doc/6/controllers/ms/pexpireat/snippets/pexpireat.js new file mode 100644 index 000000000..3a40c7fec --- /dev/null +++ b/doc/6/controllers/ms/pexpireat/snippets/pexpireat.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + + // Prints: 1 + console.log(await kuzzle.ms.exists(['foo'])); + + // Oct. 12, 2011 + await kuzzle.ms.pexpireat('foo', 1318425955000); + + // Prints: 0 + console.log(await kuzzle.ms.exists(['foo'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/pexpireat/snippets/pexpireat.test.yml b/doc/6/controllers/ms/pexpireat/snippets/pexpireat.test.yml new file mode 100644 index 000000000..d2f23f5e8 --- /dev/null +++ b/doc/6/controllers/ms/pexpireat/snippets/pexpireat.test.yml @@ -0,0 +1,11 @@ +name: ms#pexpireat +description: Sets an expiration timestamp on a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^1$ + - ^0$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/pfadd/index.md b/doc/6/controllers/ms/pfadd/index.md new file mode 100644 index 000000000..32bc0b613 --- /dev/null +++ b/doc/6/controllers/ms/pfadd/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: pfadd +--- + +# pfadd + +Adds elements to a [HyperLogLog](https://en.wikipedia.org/wiki/HyperLogLog) data structure. + +[[_Redis documentation_]](https://redis.io/commands/pfadd) + +## Arguments + +```js +pfadd(key, elements, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| HyperLogLog key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Returns a boolean telling whether the addition altered the HyperLogLog structure or not. + +## Usage + +<<< ./snippets/pfadd.js diff --git a/doc/6/controllers/ms/pfadd/snippets/pfadd.js b/doc/6/controllers/ms/pfadd/snippets/pfadd.js new file mode 100644 index 000000000..26c01e1bb --- /dev/null +++ b/doc/6/controllers/ms/pfadd/snippets/pfadd.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.pfadd('hllfoo', ['foo', 'bar', 'baz', 'qux']); + + // Prints: 4 + console.log(await kuzzle.ms.pfcount('hllfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/pfadd/snippets/pfadd.test.yml b/doc/6/controllers/ms/pfadd/snippets/pfadd.test.yml new file mode 100644 index 000000000..a471b2507 --- /dev/null +++ b/doc/6/controllers/ms/pfadd/snippets/pfadd.test.yml @@ -0,0 +1,9 @@ +name: ms#pfadd +description: Adds elements to a HyperLogLog data structure +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^4$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/pfcount/index.md b/doc/6/controllers/ms/pfcount/index.md new file mode 100644 index 000000000..e6e8245eb --- /dev/null +++ b/doc/6/controllers/ms/pfcount/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: pfcount +--- + +# pfcount + +Returns the probabilistic cardinality of a [HyperLogLog](https://en.wikipedia.org/wiki/HyperLogLog) data structure, or of the merged HyperLogLog structures if more than 1 is provided (see [pfadd](/sdk/js/6/controllers/ms/pfadd)). + +[[_Redis documentation_]](https://redis.io/commands/pfcount) + +## Arguments + +```js +pfcount(keys, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `keys` | 
string[]
| List of HyperLogLog keys | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the merged HyperLogLog structures cardinality. + +## Usage + +<<< ./snippets/pfcount.js diff --git a/doc/6/controllers/ms/pfcount/snippets/pfcount.js b/doc/6/controllers/ms/pfcount/snippets/pfcount.js new file mode 100644 index 000000000..53871f22e --- /dev/null +++ b/doc/6/controllers/ms/pfcount/snippets/pfcount.js @@ -0,0 +1,9 @@ +try { + await kuzzle.ms.pfadd('hllfoo', ['foo', 'bar', 'baz']); + await kuzzle.ms.pfadd('hllfoo2', ['hello', 'world', 'foo']); + + // Prints: 5 + console.log(await kuzzle.ms.pfcount(['hllfoo', 'hllfoo2'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/pfcount/snippets/pfcount.test.yml b/doc/6/controllers/ms/pfcount/snippets/pfcount.test.yml new file mode 100644 index 000000000..e172ba101 --- /dev/null +++ b/doc/6/controllers/ms/pfcount/snippets/pfcount.test.yml @@ -0,0 +1,9 @@ +name: ms#pfcount +description: Returns the probabilistic cardinality of a HyperLogLog data structure +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^5$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/pfmerge/index.md b/doc/6/controllers/ms/pfmerge/index.md new file mode 100644 index 000000000..ed883f3f0 --- /dev/null +++ b/doc/6/controllers/ms/pfmerge/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: pfmerge +--- + +# pfmerge + +Merges multiple [HyperLogLog](https://en.wikipedia.org/wiki/HyperLogLog) data structures into an unique HyperLogLog structure, approximating the cardinality of the union of the source structures. + +[[_Redis documentation_]](https://redis.io/commands/pfmerge) + +## Arguments + +```js +pfmerge(dest, sources, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | --------------------------------- | +| `dest` | 
string
| Destination key | +| `sources` | 
string[]
| List of HyperLogLog keys to merge | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves once the operation succeeds. + +## Usage + +<<< ./snippets/pfmerge.js diff --git a/doc/6/controllers/ms/pfmerge/snippets/pfmerge.js b/doc/6/controllers/ms/pfmerge/snippets/pfmerge.js new file mode 100644 index 000000000..3e186cba6 --- /dev/null +++ b/doc/6/controllers/ms/pfmerge/snippets/pfmerge.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.pfadd('hllfoo', ['foo', 'bar', 'baz']); + await kuzzle.ms.pfadd('hllfoo2', ['hello', 'world', 'foo']); + + await kuzzle.ms.pfmerge('hllmerged', ['hllfoo', 'hllfoo2']); + + // Prints: 5 + console.log(await kuzzle.ms.pfcount(['hllmerged'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/pfmerge/snippets/pfmerge.test.yml b/doc/6/controllers/ms/pfmerge/snippets/pfmerge.test.yml new file mode 100644 index 000000000..aa7772bda --- /dev/null +++ b/doc/6/controllers/ms/pfmerge/snippets/pfmerge.test.yml @@ -0,0 +1,9 @@ +name: ms#pfmerge +description: Merges multiple HyperLogLog data structures +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^5$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/ping/index.md b/doc/6/controllers/ms/ping/index.md new file mode 100644 index 000000000..fb757401c --- /dev/null +++ b/doc/6/controllers/ms/ping/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: ping +--- + +# ping + +Pings the memory storage database. + +[[_Redis documentation_]](https://redis.io/commands/ping) + +## Arguments + +```js +ping([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the string `PONG`. + +## Usage + +<<< ./snippets/ping.js diff --git a/doc/6/controllers/ms/ping/snippets/ping.js b/doc/6/controllers/ms/ping/snippets/ping.js new file mode 100644 index 000000000..0290c406a --- /dev/null +++ b/doc/6/controllers/ms/ping/snippets/ping.js @@ -0,0 +1,6 @@ +try { + // Prints: PONG + console.log(await kuzzle.ms.ping()); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/ping/snippets/ping.test.yml b/doc/6/controllers/ms/ping/snippets/ping.test.yml new file mode 100644 index 000000000..2de8803ee --- /dev/null +++ b/doc/6/controllers/ms/ping/snippets/ping.test.yml @@ -0,0 +1,9 @@ +name: ms#ping +description: Pings the memory storage database +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^PONG$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/psetex/index.md b/doc/6/controllers/ms/psetex/index.md new file mode 100644 index 000000000..587999708 --- /dev/null +++ b/doc/6/controllers/ms/psetex/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: psetex +--- + +# psetex + +Sets a key with the provided value, and an expiration delay expressed in milliseconds. If the key does not exist, it is created beforehand. + +[[_Redis documentation_]](https://redis.io/commands/psetex) + +## Arguments + +```js +psetex(key, value, milliseconds, [options]); +``` + +
+ +| Arguments | Type | Description | +| -------------- | ------------------ | ----------------------------------------------------- | +| `key` | 
string
| Key | +| `value` | 
string
| Value | +| `milliseconds` | 
integer
| Number of milliseconds after which the key is deleted | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves once the operation succeeds. + +## Usage + +<<< ./snippets/psetex.js diff --git a/doc/6/controllers/ms/psetex/snippets/psetex.js b/doc/6/controllers/ms/psetex/snippets/psetex.js new file mode 100644 index 000000000..f23cc7ffc --- /dev/null +++ b/doc/6/controllers/ms/psetex/snippets/psetex.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.psetex('foo', 'bar', 60000); + + // Prints: 60 + console.log(await kuzzle.ms.ttl('foo')); + + // Prints: bar + console.log(await kuzzle.ms.get('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/psetex/snippets/psetex.test.yml b/doc/6/controllers/ms/psetex/snippets/psetex.test.yml new file mode 100644 index 000000000..e18aafc99 --- /dev/null +++ b/doc/6/controllers/ms/psetex/snippets/psetex.test.yml @@ -0,0 +1,11 @@ +name: ms#psetex +description: Sets a key with the provided value, and an expiration delay expressed in milliseconds +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^[0-9]{1,2}$ + - ^bar$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/pttl/index.md b/doc/6/controllers/ms/pttl/index.md new file mode 100644 index 000000000..477790477 --- /dev/null +++ b/doc/6/controllers/ms/pttl/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: pttl +--- + +# pttl + +Returns the remaining time to live of a key, in milliseconds. + +[[_Redis documentation_]](https://redis.io/commands/pttl) + +## Arguments + +```js +pttl(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the remaining TTL, in milliseconds. + +## Usage + +<<< ./snippets/pttl.js diff --git a/doc/6/controllers/ms/pttl/snippets/pttl.js b/doc/6/controllers/ms/pttl/snippets/pttl.js new file mode 100644 index 000000000..acec88d99 --- /dev/null +++ b/doc/6/controllers/ms/pttl/snippets/pttl.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.psetex('foo', 'bar', 60000); + + // Prints: 60000 + console.log(await kuzzle.ms.pttl('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/pttl/snippets/pttl.test.yml b/doc/6/controllers/ms/pttl/snippets/pttl.test.yml new file mode 100644 index 000000000..f7881e2fd --- /dev/null +++ b/doc/6/controllers/ms/pttl/snippets/pttl.test.yml @@ -0,0 +1,9 @@ +name: ms#pttl +description: Returns the remaining time to live of a key, in milliseconds +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^[0-9]+$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/randomkey/index.md b/doc/6/controllers/ms/randomkey/index.md new file mode 100644 index 000000000..b3eea2ef2 --- /dev/null +++ b/doc/6/controllers/ms/randomkey/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: randomkey +--- + +# randomkey + +Returns a key identifier from the memory storage, at random. + +[[_Redis documentation_]](https://redis.io/commands/randomkey) + +## Arguments + +```js +randomkey([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a key identifier, at random. + +## Usage + +<<< ./snippets/randomkey.js diff --git a/doc/6/controllers/ms/randomkey/snippets/randomkey.js b/doc/6/controllers/ms/randomkey/snippets/randomkey.js new file mode 100644 index 000000000..4be04bc03 --- /dev/null +++ b/doc/6/controllers/ms/randomkey/snippets/randomkey.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.set('foo', 'val'); + await kuzzle.ms.set('bar', 'val'); + await kuzzle.ms.set('baz', 'val'); + + // Prints one of the following: foo, bar or baz + console.log(await kuzzle.ms.randomkey()); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/randomkey/snippets/randomkey.test.yml b/doc/6/controllers/ms/randomkey/snippets/randomkey.test.yml new file mode 100644 index 000000000..93c2f889c --- /dev/null +++ b/doc/6/controllers/ms/randomkey/snippets/randomkey.test.yml @@ -0,0 +1,9 @@ +name: ms#randomkey +description: Returns a key identifier from the memory storage, at random +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^(foo|bar|baz)$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/rename/index.md b/doc/6/controllers/ms/rename/index.md new file mode 100644 index 000000000..abff9ad35 --- /dev/null +++ b/doc/6/controllers/ms/rename/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: rename +--- + +# rename + +Renames a key. + +If the new key name is already used, then it is overwritten. + +[[_Redis documentation_]](https://redis.io/commands/rename) + +## Arguments + +```js +rename(src, dest, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `src` | 
string
| Key to rename | +| `dest` | 
string
| New key name | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves once the operation succeeds. + +## Usage + +<<< ./snippets/rename.js diff --git a/doc/6/controllers/ms/rename/snippets/rename.js b/doc/6/controllers/ms/rename/snippets/rename.js new file mode 100644 index 000000000..d5da37409 --- /dev/null +++ b/doc/6/controllers/ms/rename/snippets/rename.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.set('foo', 'World'); + + await kuzzle.ms.rename('foo', 'Hello'); + + // Prints: World + console.log(await kuzzle.ms.get('Hello')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/rename/snippets/rename.test.yml b/doc/6/controllers/ms/rename/snippets/rename.test.yml new file mode 100644 index 000000000..e11268290 --- /dev/null +++ b/doc/6/controllers/ms/rename/snippets/rename.test.yml @@ -0,0 +1,9 @@ +name: ms#rename +description: Renames a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^World$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/renamenx/index.md b/doc/6/controllers/ms/renamenx/index.md new file mode 100644 index 000000000..48edab3a6 --- /dev/null +++ b/doc/6/controllers/ms/renamenx/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: renamenx +--- + +# renamenx + +Renames a key, only if the new name is not already used. + +[[_Redis documentation_]](https://redis.io/commands/renamenx) + +## Arguments + +```js +renamenx(src, dest, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `src` | 
string
| Key to rename | +| `dest` | 
string
| New key name | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean telling whether the operation succeeded or not. + +## Usage + +<<< ./snippets/renamenx.js diff --git a/doc/6/controllers/ms/renamenx/snippets/renamenx.js b/doc/6/controllers/ms/renamenx/snippets/renamenx.js new file mode 100644 index 000000000..f0e9cf95e --- /dev/null +++ b/doc/6/controllers/ms/renamenx/snippets/renamenx.js @@ -0,0 +1,13 @@ +try { + await kuzzle.ms.set('foo', 'val'); + await kuzzle.ms.set('bar', 'val'); + + // Prints: false + // (the key "bar" already exists) + console.log(await kuzzle.ms.renamenx('foo', 'bar')); + + // Prints: true + console.log(await kuzzle.ms.renamenx('foo', 'qux')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/renamenx/snippets/renamenx.test.yml b/doc/6/controllers/ms/renamenx/snippets/renamenx.test.yml new file mode 100644 index 000000000..737877950 --- /dev/null +++ b/doc/6/controllers/ms/renamenx/snippets/renamenx.test.yml @@ -0,0 +1,11 @@ +name: ms#renamenx +description: Renames a key, only if the new name is not already used +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^false$ + - ^true$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/rpop/index.md b/doc/6/controllers/ms/rpop/index.md new file mode 100644 index 000000000..fb8f554ad --- /dev/null +++ b/doc/6/controllers/ms/rpop/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: rpop +--- + +# rpop + +Removes the last element of a list and returns it. + +[[_Redis documentation_]](https://redis.io/commands/rpop) + +## Arguments + +```js +rpop(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| List key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the removed element. + +## Usage + +<<< ./snippets/rpop.js diff --git a/doc/6/controllers/ms/rpop/snippets/rpop.js b/doc/6/controllers/ms/rpop/snippets/rpop.js new file mode 100644 index 000000000..906b67e2c --- /dev/null +++ b/doc/6/controllers/ms/rpop/snippets/rpop.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'baz']); + + // Prints: 'baz' + console.log(await kuzzle.ms.rpop('listfoo')); + + // Prints: [ 'foo', 'bar' ] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/rpop/snippets/rpop.test.yml b/doc/6/controllers/ms/rpop/snippets/rpop.test.yml new file mode 100644 index 000000000..77caeb66e --- /dev/null +++ b/doc/6/controllers/ms/rpop/snippets/rpop.test.yml @@ -0,0 +1,11 @@ +name: ms#rpop +description: Removes the last element of a list and returns it +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^baz$ + - "\\[ 'foo', 'bar' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/rpoplpush/index.md b/doc/6/controllers/ms/rpoplpush/index.md new file mode 100644 index 000000000..a46882b6e --- /dev/null +++ b/doc/6/controllers/ms/rpoplpush/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: rpoplpush +--- + +# rpoplpush + +Removes the last element of a list, and pushes it back at the start of another list. + +[[_Redis documentation_]](https://redis.io/commands/rpoplpush) + +## Arguments + +```js +rpoplpush(src, dest, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `src` | 
string
| Source key | +| `dest` | 
string
| Destination key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the value of the moved element. + +## Usage + +<<< ./snippets/rpoplpush.js diff --git a/doc/6/controllers/ms/rpoplpush/snippets/rpoplpush.js b/doc/6/controllers/ms/rpoplpush/snippets/rpoplpush.js new file mode 100644 index 000000000..b5ed73dca --- /dev/null +++ b/doc/6/controllers/ms/rpoplpush/snippets/rpoplpush.js @@ -0,0 +1,12 @@ +try { + await kuzzle.ms.rpush('foo', ['rick', 'astley', 'never']); + await kuzzle.ms.rpush('bar', ['gonna', 'give', 'you', 'up']); + + // Prints: never + console.log(await kuzzle.ms.rpoplpush('foo', 'bar')); + + // Prints: [ 'never', 'gonna', 'give', 'you', 'up' ] + console.log(await kuzzle.ms.lrange('bar', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/rpoplpush/snippets/rpoplpush.test.yml b/doc/6/controllers/ms/rpoplpush/snippets/rpoplpush.test.yml new file mode 100644 index 000000000..b41b74666 --- /dev/null +++ b/doc/6/controllers/ms/rpoplpush/snippets/rpoplpush.test.yml @@ -0,0 +1,11 @@ +name: ms#rpoplpush +description: Removes the last element of a list, and pushes it back at the start of another list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^never$ + - "\\[ 'never', 'gonna', 'give', 'you', 'up' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/rpush/index.md b/doc/6/controllers/ms/rpush/index.md new file mode 100644 index 000000000..becc1860e --- /dev/null +++ b/doc/6/controllers/ms/rpush/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: rpush +--- + +# rpush + +Appends values at the end of a list. + +If the destination list does not exist, it is created holding an empty list before performing the operation. + +[[_Redis documentation_]](https://redis.io/commands/rpush) + +## Arguments + +```js +rpush(key, values, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `key` | 
string
| List key | +| `values` | 
string[]
| List of values to append | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated list length. + +## Usage + +<<< ./snippets/rpush.js diff --git a/doc/6/controllers/ms/rpush/snippets/rpush.js b/doc/6/controllers/ms/rpush/snippets/rpush.js new file mode 100644 index 000000000..d6cd12b16 --- /dev/null +++ b/doc/6/controllers/ms/rpush/snippets/rpush.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'baz']); + + // Prints: [ 'foo', 'bar', 'baz' ] + console.log(await kuzzle.ms.lrange('listfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/rpush/snippets/rpush.test.yml b/doc/6/controllers/ms/rpush/snippets/rpush.test.yml new file mode 100644 index 000000000..d68827600 --- /dev/null +++ b/doc/6/controllers/ms/rpush/snippets/rpush.test.yml @@ -0,0 +1,9 @@ +name: ms#rpush +description: Appends values at the end of a list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'foo', 'bar', 'baz' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/rpushx/index.md b/doc/6/controllers/ms/rpushx/index.md new file mode 100644 index 000000000..f9604b8c1 --- /dev/null +++ b/doc/6/controllers/ms/rpushx/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: rpushx +--- + +# rpushx + +Appends a value at the end of a list, only if the destination key already exists, and if it holds a list. + +[[_Redis documentation_]](https://redis.io/commands/rpushx) + +## Arguments + +```js +rpushx(key, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| List key | +| `value` | 
string
| Value to append | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated list length. + +## Usage + +<<< ./snippets/rpushx.js diff --git a/doc/6/controllers/ms/rpushx/snippets/rpushx.js b/doc/6/controllers/ms/rpushx/snippets/rpushx.js new file mode 100644 index 000000000..00875bb69 --- /dev/null +++ b/doc/6/controllers/ms/rpushx/snippets/rpushx.js @@ -0,0 +1,12 @@ +try { + // Prints: 0 + // ("listfoo" does not exist: the operation fails) + console.log(await kuzzle.ms.rpushx('listfoo', 'qux')); + + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'baz']); + + // Prints: 4 + console.log(await kuzzle.ms.rpushx('listfoo', 'qux')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/rpushx/snippets/rpushx.test.yml b/doc/6/controllers/ms/rpushx/snippets/rpushx.test.yml new file mode 100644 index 000000000..af30e7bb7 --- /dev/null +++ b/doc/6/controllers/ms/rpushx/snippets/rpushx.test.yml @@ -0,0 +1,11 @@ +name: ms#rpushx +description: Appends a value at the end of an existing list +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^0$ + - ^4$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sadd/index.md b/doc/6/controllers/ms/sadd/index.md new file mode 100644 index 000000000..cf3f528d0 --- /dev/null +++ b/doc/6/controllers/ms/sadd/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: sadd +--- + +# sadd + +Adds members to a set of unique values stored at `key`. + +If the destination set does not exist, it is created beforehand. + +[[_Redis documentation_]](https://redis.io/commands/sadd) + +## Arguments + +```js +sadd(key, values, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `key` | 
string
| Set key | +| `values` | 
string[]
| Values to add | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of successfully added members. + +## Usage + +<<< ./snippets/sadd.js diff --git a/doc/6/controllers/ms/sadd/snippets/sadd.js b/doc/6/controllers/ms/sadd/snippets/sadd.js new file mode 100644 index 000000000..0af225de5 --- /dev/null +++ b/doc/6/controllers/ms/sadd/snippets/sadd.js @@ -0,0 +1,12 @@ +try { + // Prints: 2 + console.log(await kuzzle.ms.sadd('setfoo', ['foo', 'bar'])); + + // Prints: 1 + console.log(await kuzzle.ms.sadd('setfoo', ['foo', 'bar', 'baz'])); + + // Prints: [ 'foo', 'bar', 'baz' ] + console.log(await kuzzle.ms.smembers('setfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sadd/snippets/sadd.test.yml b/doc/6/controllers/ms/sadd/snippets/sadd.test.yml new file mode 100644 index 000000000..a66e0e5d4 --- /dev/null +++ b/doc/6/controllers/ms/sadd/snippets/sadd.test.yml @@ -0,0 +1,12 @@ +name: ms#sadd +description: Adds members to a set of unique values stored at key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^2$ + - ^1$ + - "\\[ '(foo|bar|baz)', '(foo|bar|baz)', '(foo|bar|baz)' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/scan/index.md b/doc/6/controllers/ms/scan/index.md new file mode 100644 index 000000000..9ba928872 --- /dev/null +++ b/doc/6/controllers/ms/scan/index.md @@ -0,0 +1,52 @@ +--- +code: true +type: page +title: scan +--- + +# scan + +Iterates incrementally over the set of keys in the database using a cursor. + +An iteration starts when the cursor is set to 0. +To get the next page of results, simply re-send the request with the updated cursor position provided in the result set. + +The scan ends when the cursor returned by the server is 0. + +[[_Redis documentation_]](https://redis.io/commands/scan) + +## Arguments + +```js +scan(cursor, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ------------------------ | +| `cursor` | 
integer
| Cursor offset | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `count` | 
integer (10)
| Return an _approximate_ number of items per result set | +| `match` | 
string (\*)
| Return only keys matching the provided pattern | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an object representing a result page, with the following properties: + +| Property | Type | Description | +| -------- | ------------------- | ----------------------------------------------------------------- | +| `cursor` | 
integer
| Cursor offset for the next page, or `0` if at the end of the scan | +| `values` | 
string[]
| List of keys | + +## Usage + +<<< ./snippets/scan.js diff --git a/doc/6/controllers/ms/scan/snippets/scan.js b/doc/6/controllers/ms/scan/snippets/scan.js new file mode 100644 index 000000000..1eb7f8c56 --- /dev/null +++ b/doc/6/controllers/ms/scan/snippets/scan.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.set('key1', 'val1'); + await kuzzle.ms.set('key2', 'val2'); + await kuzzle.ms.set('key3', 'val3'); + + // Prints: + // { + // cursor: '0', + // values: [ 'key1', 'key2', 'key3' ] + // } + console.log(await kuzzle.ms.scan(0)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/scan/snippets/scan.test.yml b/doc/6/controllers/ms/scan/snippets/scan.test.yml new file mode 100644 index 000000000..94f14acf7 --- /dev/null +++ b/doc/6/controllers/ms/scan/snippets/scan.test.yml @@ -0,0 +1,11 @@ +name: ms#scan +description: Iterates incrementally over the set of keys in the database using a cursor +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "{ cursor: '0', values: \\[ 'key[123]', 'key[123]', 'key[123]' ] }" + +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/scard/index.md b/doc/6/controllers/ms/scard/index.md new file mode 100644 index 000000000..f7b7aca95 --- /dev/null +++ b/doc/6/controllers/ms/scard/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: scard +--- + +# scard + +Returns the number of members stored in a set of unique values. + +[[_Redis documentation_]](https://redis.io/commands/scard) + +## Arguments + +```js +scard(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Set key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the set length. + +## Usage + +<<< ./snippets/scard.js diff --git a/doc/6/controllers/ms/scard/snippets/scard.js b/doc/6/controllers/ms/scard/snippets/scard.js new file mode 100644 index 000000000..66850ad3e --- /dev/null +++ b/doc/6/controllers/ms/scard/snippets/scard.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.sadd('setfoo', ['foo', 'foo', 'bar', 'baz']); + + // Prints: 3 + console.log(await kuzzle.ms.scard('setfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/scard/snippets/scard.test.yml b/doc/6/controllers/ms/scard/snippets/scard.test.yml new file mode 100644 index 000000000..233e97519 --- /dev/null +++ b/doc/6/controllers/ms/scard/snippets/scard.test.yml @@ -0,0 +1,9 @@ +name: ms#scard +description: Returns the number of members stored in a set of unique values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^3$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sdiff/index.md b/doc/6/controllers/ms/sdiff/index.md new file mode 100644 index 000000000..06f361efe --- /dev/null +++ b/doc/6/controllers/ms/sdiff/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: sdiff +--- + +# sdiff + +Returns the difference between a reference set and a list of other sets. + +[[_Redis documentation_]](https://redis.io/commands/sdiff) + +## Arguments + +```js +sdiff(ref, sets, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ---------------------------------------- | +| `ref` | 
string
| Set key of reference | +| `sets` | 
string[]
| List of sets to compare to the reference | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an array of differences. + +## Usage + +<<< ./snippets/sdiff.js diff --git a/doc/6/controllers/ms/sdiff/snippets/sdiff.js b/doc/6/controllers/ms/sdiff/snippets/sdiff.js new file mode 100644 index 000000000..81554c2b2 --- /dev/null +++ b/doc/6/controllers/ms/sdiff/snippets/sdiff.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.sadd('ref', ['foo', 'bar', 'baz']); + + await kuzzle.ms.sadd('set1', ['foo', 'hello']); + await kuzzle.ms.sadd('set2', ['bar', 'world']); + + // Prints: [ 'baz' ] + console.log(await kuzzle.ms.sdiff('ref', ['set1', 'set2'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sdiff/snippets/sdiff.test.yml b/doc/6/controllers/ms/sdiff/snippets/sdiff.test.yml new file mode 100644 index 000000000..f828fae8b --- /dev/null +++ b/doc/6/controllers/ms/sdiff/snippets/sdiff.test.yml @@ -0,0 +1,9 @@ +name: ms#sdiff +description: Returns the difference between a reference set and a list of other sets +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'baz' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sdiffstore/index.md b/doc/6/controllers/ms/sdiffstore/index.md new file mode 100644 index 000000000..5fb7807b3 --- /dev/null +++ b/doc/6/controllers/ms/sdiffstore/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: sdiffstore +--- + +# sdiffstore + +Computes the difference between a reference set of unique values, and other sets. The differences are then stored in the provided destination key. + +If the destination key already exists, it is overwritten. + +[[_Redis documentation_]](https://redis.io/commands/sdiffstore) + +## Arguments + +```js +sdiffstore(ref, sets, dest, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ---------------------------------------- | +| `ref` | 
string
| Set key of reference | +| `sets` | 
string[]
| List of sets to compare to the reference | +| `dest` | 
string
| Destination key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of values stored at the new key. + +## Usage + +<<< ./snippets/sdiffstore.js diff --git a/doc/6/controllers/ms/sdiffstore/snippets/sdiffstore.js b/doc/6/controllers/ms/sdiffstore/snippets/sdiffstore.js new file mode 100644 index 000000000..cffbb2826 --- /dev/null +++ b/doc/6/controllers/ms/sdiffstore/snippets/sdiffstore.js @@ -0,0 +1,13 @@ +try { + await kuzzle.ms.sadd('ref', ['foo', 'bar', 'baz']); + + await kuzzle.ms.sadd('set1', ['foo', 'hello']); + await kuzzle.ms.sadd('set2', ['bar', 'world']); + + await kuzzle.ms.sdiffstore('ref', ['set1', 'set2'], 'diffs'); + + // Prints: [ 'baz' ] + console.log(await kuzzle.ms.smembers('diffs')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sdiffstore/snippets/sdiffstore.test.yml b/doc/6/controllers/ms/sdiffstore/snippets/sdiffstore.test.yml new file mode 100644 index 000000000..fdbc89b7f --- /dev/null +++ b/doc/6/controllers/ms/sdiffstore/snippets/sdiffstore.test.yml @@ -0,0 +1,9 @@ +name: ms#sdiffstore +description: Stores the difference between a reference set and a list of other sets in a new key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'baz' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/set/index.md b/doc/6/controllers/ms/set/index.md new file mode 100644 index 000000000..35300d86b --- /dev/null +++ b/doc/6/controllers/ms/set/index.md @@ -0,0 +1,47 @@ +--- +code: true +type: page +title: set +--- + +# set + +Creates a key holding the provided value, or overwrites it if it already exists. + +[[_Redis documentation_]](https://redis.io/commands/set) + +## Arguments + +```js +set(key, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `value` | 
\*
| Value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | -------------------------- | ---------------------------------------------------------------------------- | +| `ex` | 
integer
| Adds an expiration delay to the key, in seconds | +| `nx` | 
boolean (false)
| If true, do not set the key if it already exists | +| `px` | 
integer
| Adds an expiration delay to the key, in milliseconds | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | +| `xx` | 
boolean (false)
| If true, sets the key only if it already exists | + +Note: the `ex` and `px` options are mutually exclusive; setting both options ends up in a `BadRequestError` error. Same thing goes for `nx` and `xx`. + +## Resolve + +Resolves once the operation succeeds. + +## Usage + +<<< ./snippets/set.js diff --git a/doc/6/controllers/ms/set/snippets/set.js b/doc/6/controllers/ms/set/snippets/set.js new file mode 100644 index 000000000..3f26ee695 --- /dev/null +++ b/doc/6/controllers/ms/set/snippets/set.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + + // Prints: bar + console.log(await kuzzle.ms.get('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/set/snippets/set.test.yml b/doc/6/controllers/ms/set/snippets/set.test.yml new file mode 100644 index 000000000..48ccb56e6 --- /dev/null +++ b/doc/6/controllers/ms/set/snippets/set.test.yml @@ -0,0 +1,9 @@ +name: ms#set +description: Creates a key holding the provided value, or overwrites it if it already exists +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^bar$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/setex/index.md b/doc/6/controllers/ms/setex/index.md new file mode 100644 index 000000000..239c83543 --- /dev/null +++ b/doc/6/controllers/ms/setex/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: setex +--- + +# setex + +Sets a value and a time to live (in seconds) on a key. If the key already exists, it is overwritten. + +[[_Redis documentation_]](https://redis.io/commands/setex) + +## Arguments + +```js +setex(key, value, seconds, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ------------------------------------------------ | +| `key` | 
string
| Key | +| `value` | 
string
| Value | +| `seconds` | 
integer
| Number of seconds after which the key is deleted | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves once the operation succeeds. + +## Usage + +<<< ./snippets/setex.js diff --git a/doc/6/controllers/ms/setex/snippets/setex.js b/doc/6/controllers/ms/setex/snippets/setex.js new file mode 100644 index 000000000..a51b2eedc --- /dev/null +++ b/doc/6/controllers/ms/setex/snippets/setex.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.setex('foo', 'bar', 60); + + // Prints: 60 + console.log(await kuzzle.ms.ttl('foo')); + + // Prints: bar + console.log(await kuzzle.ms.get('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/setex/snippets/setex.test.yml b/doc/6/controllers/ms/setex/snippets/setex.test.yml new file mode 100644 index 000000000..2e27369b8 --- /dev/null +++ b/doc/6/controllers/ms/setex/snippets/setex.test.yml @@ -0,0 +1,11 @@ +name: ms#setex +description: Sets a value and a time to live (in seconds) on a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^[0-9]{1,2}$ + - ^bar$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/setnx/index.md b/doc/6/controllers/ms/setnx/index.md new file mode 100644 index 000000000..d1babbb69 --- /dev/null +++ b/doc/6/controllers/ms/setnx/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: setnx +--- + +# setnx + +Sets a value on a key, only if it does not already exist. + +[[_Redis documentation_]](https://redis.io/commands/setnx) + +## Arguments + +```js +setnx(key, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `value` | 
string
| Value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean telling if the operation succeeded or not. + +## Usage + +<<< ./snippets/setnx.js diff --git a/doc/6/controllers/ms/setnx/snippets/setnx.js b/doc/6/controllers/ms/setnx/snippets/setnx.js new file mode 100644 index 000000000..62128914b --- /dev/null +++ b/doc/6/controllers/ms/setnx/snippets/setnx.js @@ -0,0 +1,12 @@ +try { + // Prints: true + console.log(await kuzzle.ms.setnx('foo', 'bar')); + + // Prints: false + console.log(await kuzzle.ms.setnx('foo', 'qux')); + + // Prints: bar + console.log(await kuzzle.ms.get('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/setnx/snippets/setnx.test.yml b/doc/6/controllers/ms/setnx/snippets/setnx.test.yml new file mode 100644 index 000000000..7611aab3b --- /dev/null +++ b/doc/6/controllers/ms/setnx/snippets/setnx.test.yml @@ -0,0 +1,12 @@ +name: ms#setnx +description: Sets a value on a key, only if it does not already exist +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^true$ + - ^false$ + - ^bar$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sinter/index.md b/doc/6/controllers/ms/sinter/index.md new file mode 100644 index 000000000..5c439a2f1 --- /dev/null +++ b/doc/6/controllers/ms/sinter/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: sinter +--- + +# sinter + +Returns the intersection of the provided sets of unique values. + +[[_Redis documentation_]](https://redis.io/commands/sinter) + +## Arguments + +```js +sinter(keys, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ----------------------------- | +| `keys` | 
string[]
| List of set keys to intersect | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an array of intersected values. + +## Usage + +<<< ./snippets/sinter.js diff --git a/doc/6/controllers/ms/sinter/snippets/sinter.js b/doc/6/controllers/ms/sinter/snippets/sinter.js new file mode 100644 index 000000000..a6e4edaa2 --- /dev/null +++ b/doc/6/controllers/ms/sinter/snippets/sinter.js @@ -0,0 +1,9 @@ +try { + await kuzzle.ms.sadd('set1', ['foo', 'bar', 'hello']); + await kuzzle.ms.sadd('set2', ['world', 'baz', 'foo']); + + // Prints: [ 'foo' ] + console.log(await kuzzle.ms.sinter(['set1', 'set2'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sinter/snippets/sinter.test.yml b/doc/6/controllers/ms/sinter/snippets/sinter.test.yml new file mode 100644 index 000000000..f1cda41f4 --- /dev/null +++ b/doc/6/controllers/ms/sinter/snippets/sinter.test.yml @@ -0,0 +1,9 @@ +name: ms#sinter +description: Returns the intersection of the provided sets of unique values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'foo' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sinterstore/index.md b/doc/6/controllers/ms/sinterstore/index.md new file mode 100644 index 000000000..1299b6d77 --- /dev/null +++ b/doc/6/controllers/ms/sinterstore/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: sinterstore +--- + +# sinterstore + +Computes the intersection of the provided sets of unique values, and stores the result in a destination key. + +If the destination key already exists, it is overwritten. + +[[_Redis documentation_]](https://redis.io/commands/sinterstore) + +## Arguments + +```js +sinterstore(dest, keys, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ----------------------------- | +| `dest` | 
string
| Destination key | +| `keys` | 
string[]
| List of set keys to intersect | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of stored values. + +## Usage + +<<< ./snippets/sinterstore.js diff --git a/doc/6/controllers/ms/sinterstore/snippets/sinterstore.js b/doc/6/controllers/ms/sinterstore/snippets/sinterstore.js new file mode 100644 index 000000000..ddd7da447 --- /dev/null +++ b/doc/6/controllers/ms/sinterstore/snippets/sinterstore.js @@ -0,0 +1,12 @@ +try { + await kuzzle.ms.sadd('set1', ['foo', 'bar', 'hello']); + await kuzzle.ms.sadd('set2', ['world', 'baz', 'foo']); + + // Prints: 1 + console.log(await kuzzle.ms.sinterstore('dest', ['set1', 'set2'])); + + // Prints: [ 'foo' ] + console.log(await kuzzle.ms.smembers('dest')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sinterstore/snippets/sinterstore.test.yml b/doc/6/controllers/ms/sinterstore/snippets/sinterstore.test.yml new file mode 100644 index 000000000..6563fb0ab --- /dev/null +++ b/doc/6/controllers/ms/sinterstore/snippets/sinterstore.test.yml @@ -0,0 +1,11 @@ +name: ms#sinterstore +description: Stores the intersection of the provided sets of unique values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^1$ + - "\\[ 'foo' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sismember/index.md b/doc/6/controllers/ms/sismember/index.md new file mode 100644 index 000000000..dee827912 --- /dev/null +++ b/doc/6/controllers/ms/sismember/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: sismember +--- + +# sismember + +Checks if a value is a member of a set of unique values. + +[[_Redis documentation_]](https://redis.io/commands/sismember) + +## Arguments + +```js +sismember(key, value, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Set key | +| `value` | 
string
| Value to check | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean telling if the value is in the set or not. + +## Usage + +<<< ./snippets/sismember.js diff --git a/doc/6/controllers/ms/sismember/snippets/sismember.js b/doc/6/controllers/ms/sismember/snippets/sismember.js new file mode 100644 index 000000000..4ff009cc3 --- /dev/null +++ b/doc/6/controllers/ms/sismember/snippets/sismember.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.sadd('setfoo', ['foo', 'bar', 'baz']); + + // Prints: true + console.log(await kuzzle.ms.sismember('setfoo', 'bar')); + + // Prints: false + console.log(await kuzzle.ms.sismember('setfoo', 'qux')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sismember/snippets/sismember.test.yml b/doc/6/controllers/ms/sismember/snippets/sismember.test.yml new file mode 100644 index 000000000..944f3a6cc --- /dev/null +++ b/doc/6/controllers/ms/sismember/snippets/sismember.test.yml @@ -0,0 +1,11 @@ +name: ms#sismember +description: Checks if a value is a member of a set of unique values. +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^true$ + - ^false$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/smembers/index.md b/doc/6/controllers/ms/smembers/index.md new file mode 100644 index 000000000..d1273c0d0 --- /dev/null +++ b/doc/6/controllers/ms/smembers/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: smembers +--- + +# smembers + +Returns the members of a set of unique values. + +[[_Redis documentation_]](https://redis.io/commands/smembers) + +## Arguments + +```js +smembers(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Set key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the list of the set's members. + +## Usage + +<<< ./snippets/smembers.js diff --git a/doc/6/controllers/ms/smembers/snippets/smembers.js b/doc/6/controllers/ms/smembers/snippets/smembers.js new file mode 100644 index 000000000..1f94a3f2d --- /dev/null +++ b/doc/6/controllers/ms/smembers/snippets/smembers.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.sadd('listfoo', ['foo', 'bar', 'baz']); + + // Prints: [ 'foo', 'bar', 'baz' ] + console.log(await kuzzle.ms.smembers('listfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/smembers/snippets/smembers.test.yml b/doc/6/controllers/ms/smembers/snippets/smembers.test.yml new file mode 100644 index 000000000..5c4cae961 --- /dev/null +++ b/doc/6/controllers/ms/smembers/snippets/smembers.test.yml @@ -0,0 +1,9 @@ +name: ms#smembers +description: Returns the members of a set of unique values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ '(foo|bar|baz)', '(foo|bar|baz)', '(foo|bar|baz)' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/smove/index.md b/doc/6/controllers/ms/smove/index.md new file mode 100644 index 000000000..942d77bd6 --- /dev/null +++ b/doc/6/controllers/ms/smove/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: smove +--- + +# smove + +Moves a member from a set of unique values to another. + +[[_Redis documentation_]](https://redis.io/commands/smove) + +## Arguments + +```js +smove(src, dest, member, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `src` | 
string
| Source set key | +| `dest` | 
string
| Destination set key | +| `member` | 
string
| Member to move | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a boolean telling whether the operation succeeded or not. + +## Usage + +<<< ./snippets/smove.js diff --git a/doc/6/controllers/ms/smove/snippets/smove.js b/doc/6/controllers/ms/smove/snippets/smove.js new file mode 100644 index 000000000..06ddc9be0 --- /dev/null +++ b/doc/6/controllers/ms/smove/snippets/smove.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.sadd('set1', ['foo', 'bar', 'baz']); + await kuzzle.ms.sadd('set2', ['qux']); + + await kuzzle.ms.smove('set1', 'set2', 'foo'); + + // Prints: [ 'bar', 'baz' ] + console.log(await kuzzle.ms.smembers('set1')); + + // Prints: [ 'foo', 'qux' ] + console.log(await kuzzle.ms.smembers('set2')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/smove/snippets/smove.test.yml b/doc/6/controllers/ms/smove/snippets/smove.test.yml new file mode 100644 index 000000000..abbf09ca1 --- /dev/null +++ b/doc/6/controllers/ms/smove/snippets/smove.test.yml @@ -0,0 +1,11 @@ +name: ms#smove +description: Moves a member from a set of unique values to another +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ '(bar|baz)', '(bar|baz)' ]" + - "\\[ '(foo|qux)', '(foo|qux)' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sort/index.md b/doc/6/controllers/ms/sort/index.md new file mode 100644 index 000000000..e3641baa8 --- /dev/null +++ b/doc/6/controllers/ms/sort/index.md @@ -0,0 +1,46 @@ +--- +code: true +type: page +title: sort +--- + +# sort + +Sorts and returns elements contained in a list, a set of unique values or a sorted set. +By default, sorting is numeric and elements are compared by their value, interpreted as double precision floating point number. + +[[_Redis documentation_]](https://redis.io/commands/sort) + +## Arguments + +```js +sort(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | --------------------------- | +| `key` | 
string
| List, set or sorted set key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ----------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `alpha` | 
boolean (false)
| Performs an alphanumerical sort instead of a numeric one | +| `by` | 
string
| Instead of sorting by values, sorts by values contained in external keys, using the provided pattern completed by values of the list/set/sorted set to sort | +| `direction` | 
string ('ASC')
| Sorts in ascendant or descendant order.
Allowed values: `ASC`, `DESC` | +| `get` | 
string[]
| Instead of returning the sorted values directly, returns the values contained in external keys, using patterns completed by the sorted values | +| `limit` | 
integer[]
| Limits the result set to a range of matching elements (similar to _SELECT LIMIT offset, count_ in SQL).
Format: `[, ]` | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the sorted elements. + +## Usage + +<<< ./snippets/sort.js diff --git a/doc/6/controllers/ms/sort/snippets/sort.js b/doc/6/controllers/ms/sort/snippets/sort.js new file mode 100644 index 000000000..7228c23eb --- /dev/null +++ b/doc/6/controllers/ms/sort/snippets/sort.js @@ -0,0 +1,12 @@ +try { + await kuzzle.ms.sadd('setfoo', [1, 2, 3, 4, 5, 6, 7]); + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'baz', 'qux']); + + // Prints: [ '7', '6', '5', '4', '3', '2', '1' ] + console.log(await kuzzle.ms.sort('setfoo', {direction: 'DESC'})); + + // Prints: [ 'bar', 'baz', 'foo', 'qux' ] + console.log(await kuzzle.ms.sort('listfoo', {alpha: true})); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sort/snippets/sort.test.yml b/doc/6/controllers/ms/sort/snippets/sort.test.yml new file mode 100644 index 000000000..10a6a0b7e --- /dev/null +++ b/doc/6/controllers/ms/sort/snippets/sort.test.yml @@ -0,0 +1,11 @@ +name: ms#sort +description: Sorts and returns elements contained in a list, a set or a sorted set +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ '7', '6', '5', '4', '3', '2', '1' ]" + - "\\[ 'bar', 'baz', 'foo', 'qux' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/spop/index.md b/doc/6/controllers/ms/spop/index.md new file mode 100644 index 000000000..d54920635 --- /dev/null +++ b/doc/6/controllers/ms/spop/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: spop +--- + +# spop + +Removes and returns one or more elements at random from a set of unique values. + +[[_Redis documentation_]](https://redis.io/commands/spop) + +## Arguments + +```js +spop(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Set key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `count` | 
integer (1)
| The number of elements to pop | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the list of removed elements. + +## Usage + +<<< ./snippets/spop.js diff --git a/doc/6/controllers/ms/spop/snippets/spop.js b/doc/6/controllers/ms/spop/snippets/spop.js new file mode 100644 index 000000000..0b9c8886a --- /dev/null +++ b/doc/6/controllers/ms/spop/snippets/spop.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.sadd('setfoo', ['a', 'b', 'c', 'd', 'e', 'f']); + + // Prints one of the elements of setfoo, at random + console.log(await kuzzle.ms.spop('setfoo')); + + // Prints three of the remaining elements of setfoo, at random + console.log(await kuzzle.ms.spop('setfoo', {count: 3})); + + // Prints: 2 + console.log(await kuzzle.ms.scard('setfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/spop/snippets/spop.test.yml b/doc/6/controllers/ms/spop/snippets/spop.test.yml new file mode 100644 index 000000000..6fdcdadec --- /dev/null +++ b/doc/6/controllers/ms/spop/snippets/spop.test.yml @@ -0,0 +1,12 @@ +name: ms#spop +description: Removes one or more elements at random from a set of unique values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "^\\[ '[a-f]' ]" + - "^\\[ '[a-f]', '[a-f]', '[a-f]' ]" + - ^2$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/srandmember/index.md b/doc/6/controllers/ms/srandmember/index.md new file mode 100644 index 000000000..c668e4894 --- /dev/null +++ b/doc/6/controllers/ms/srandmember/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: srandmember +--- + +# srandmember + +Returns one or more members of a set of unique values, at random. + +[[_Redis documentation_]](https://redis.io/commands/srandmember) + +## Arguments + +```js +srandmember(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | -------- | ------------------------ | +| `key` | `string` | Set key | +| `options` | `object` | Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `count` | `integer (1)` | If positive, returns `count` elements at random from the set, without repetition.
If negative, returns `abs(count)` elements, and the same element can be chosen multiple times | +| `queuable` | `boolean (true)` | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +## Usage + +<<< ./snippets/srandmember.js diff --git a/doc/6/controllers/ms/srandmember/snippets/srandmember.js b/doc/6/controllers/ms/srandmember/snippets/srandmember.js new file mode 100644 index 000000000..f3a62c5bf --- /dev/null +++ b/doc/6/controllers/ms/srandmember/snippets/srandmember.js @@ -0,0 +1,12 @@ +try { + + await kuzzle.ms.sadd('setfoo', ['a', 'b', 'c', 'd', 'e', 'f']); + + // Prints one of the elements of setfoo, at random + console.log(await kuzzle.ms.srandmember('setfoo')); + + // Prints three elements of setfoo, at random + console.log(await kuzzle.ms.srandmember('setfoo', {count: 3})); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/srandmember/snippets/srandmember.test.yml b/doc/6/controllers/ms/srandmember/snippets/srandmember.test.yml new file mode 100644 index 000000000..ff393adee --- /dev/null +++ b/doc/6/controllers/ms/srandmember/snippets/srandmember.test.yml @@ -0,0 +1,11 @@ +name: ms#srandmember +description: Returns one or more members of a set of unique values, at random +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "^\\[ '[a-f]' ]" + - "^\\[ '[a-f]', '[a-f]', '[a-f]' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/srem/index.md b/doc/6/controllers/ms/srem/index.md new file mode 100644 index 000000000..d88c22c69 --- /dev/null +++ b/doc/6/controllers/ms/srem/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: srem +--- + +# srem + +Removes members from a set of unique values. + +[[_Redis documentation_]](https://redis.io/commands/srem) + +## Arguments + +```js +srem(key, members, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------- | +| `key` | 
string
| Set key | +| `members` | 
string[]
| List of members to remove | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of removed members. + +## Usage + +<<< ./snippets/srem.js diff --git a/doc/6/controllers/ms/srem/snippets/srem.js b/doc/6/controllers/ms/srem/snippets/srem.js new file mode 100644 index 000000000..2d984c745 --- /dev/null +++ b/doc/6/controllers/ms/srem/snippets/srem.js @@ -0,0 +1,11 @@ +try { + await kuzzle.ms.sadd('setfoo', ['foo', 'bar', 'baz']); + + // Prints: 2 + console.log(await kuzzle.ms.srem('setfoo', ['bar', 'baz'])); + + // Prints: ['foo'] + console.log(await kuzzle.ms.smembers('setfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/srem/snippets/srem.test.yml b/doc/6/controllers/ms/srem/snippets/srem.test.yml new file mode 100644 index 000000000..788fb56b0 --- /dev/null +++ b/doc/6/controllers/ms/srem/snippets/srem.test.yml @@ -0,0 +1,11 @@ +name: ms#srem +description: Removes members from a set of unique values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^2$ + - "\\[ 'foo' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sscan/index.md b/doc/6/controllers/ms/sscan/index.md new file mode 100644 index 000000000..a862588a9 --- /dev/null +++ b/doc/6/controllers/ms/sscan/index.md @@ -0,0 +1,53 @@ +--- +code: true +type: page +title: sscan +--- + +# sscan + +Iterates incrementally over members contained in a set of unique values, using a cursor. + +An iteration starts when the cursor is set to 0. +To get the next page of results, simply re-send the request with the updated cursor position provided in the result set. + +The scan ends when the cursor returned by the server is 0. + +[[_Redis documentation_]](https://redis.io/commands/sscan) + +## Arguments + +```js +sscan(key, cursor, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ------------------------ | +| `key` | 
string
| Set key | +| `cursor` | 
integer
| Cursor offset | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `count` | 
integer (10)
| Return an _approximate_ number of items per result set | +| `match` | 
string (\*)
| Return only keys matching the provided pattern | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an object representing a result page, with the following properties: + +| Property | Type | Description | +| -------- | ------------------- | ----------------------------------------------------------------- | +| `cursor` | 
integer
| Cursor offset for the next page, or `0` if at the end of the scan | +| `values` | 
string[]
| List of found members | + +## Usage + +<<< ./snippets/sscan.js diff --git a/doc/6/controllers/ms/sscan/snippets/sscan.js b/doc/6/controllers/ms/sscan/snippets/sscan.js new file mode 100644 index 000000000..05121a1f9 --- /dev/null +++ b/doc/6/controllers/ms/sscan/snippets/sscan.js @@ -0,0 +1,12 @@ +try { + await kuzzle.ms.sadd('setfoo', ['foo', 'bar', 'baz']); + + // Prints: + // { + // cursor: '0', + // values: [ bar', 'baz' ] + // } + console.log(await kuzzle.ms.sscan('setfoo', 0, {match: 'ba*'})); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sscan/snippets/sscan.test.yml b/doc/6/controllers/ms/sscan/snippets/sscan.test.yml new file mode 100644 index 000000000..30984934a --- /dev/null +++ b/doc/6/controllers/ms/sscan/snippets/sscan.test.yml @@ -0,0 +1,11 @@ +name: ms#sscan +description: Iterates incrementally over members contained in a set of unique values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "{ cursor: '0', values: \\[ 'ba[rz]', 'ba[rz]' ] }" + +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/strlen/index.md b/doc/6/controllers/ms/strlen/index.md new file mode 100644 index 000000000..f08e8a8aa --- /dev/null +++ b/doc/6/controllers/ms/strlen/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: strlen +--- + +# strlen + +Returns the length of a value. + +[[_Redis documentation_]](https://redis.io/commands/strlen) + +## Arguments + +```js +strlen(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the value's length. + +## Usage + +<<< ./snippets/strlen.js diff --git a/doc/6/controllers/ms/strlen/snippets/strlen.js b/doc/6/controllers/ms/strlen/snippets/strlen.js new file mode 100644 index 000000000..1fd6d1890 --- /dev/null +++ b/doc/6/controllers/ms/strlen/snippets/strlen.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('foo', 'abcdef'); + + // Prints: 6 + console.log(await kuzzle.ms.strlen('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/strlen/snippets/strlen.test.yml b/doc/6/controllers/ms/strlen/snippets/strlen.test.yml new file mode 100644 index 000000000..de4defc7b --- /dev/null +++ b/doc/6/controllers/ms/strlen/snippets/strlen.test.yml @@ -0,0 +1,9 @@ +name: ms#strlen +description: Returns the length of a value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^6$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sunion/index.md b/doc/6/controllers/ms/sunion/index.md new file mode 100644 index 000000000..d7e68457f --- /dev/null +++ b/doc/6/controllers/ms/sunion/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: sunion +--- + +# sunion + +Returns the union of sets of unique values. + +[[_Redis documentation_]](https://redis.io/commands/sunion) + +## Arguments + +```js +sunion(keys, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `keys` | 
string[]
| List of set keys | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the result of the union between the provided sets. + +## Usage + +<<< ./snippets/sunion.js diff --git a/doc/6/controllers/ms/sunion/snippets/sunion.js b/doc/6/controllers/ms/sunion/snippets/sunion.js new file mode 100644 index 000000000..3e414c706 --- /dev/null +++ b/doc/6/controllers/ms/sunion/snippets/sunion.js @@ -0,0 +1,10 @@ +try { + await kuzzle.ms.sadd('set1', ['a', 'b', 'c']); + await kuzzle.ms.sadd('set2', ['d', 'e', 'f']); + await kuzzle.ms.sadd('set3', ['g', 'h', 'i']); + + // Prints: [ 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i' ] + console.log(await kuzzle.ms.sunion(['set1', 'set2', 'set3'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sunion/snippets/sunion.test.yml b/doc/6/controllers/ms/sunion/snippets/sunion.test.yml new file mode 100644 index 000000000..14b73c511 --- /dev/null +++ b/doc/6/controllers/ms/sunion/snippets/sunion.test.yml @@ -0,0 +1,9 @@ +name: ms#sunion +description: Returns the union of sets of unique values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ ('[a-i]', ){8}'[a-i]' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/sunionstore/index.md b/doc/6/controllers/ms/sunionstore/index.md new file mode 100644 index 000000000..7557d9759 --- /dev/null +++ b/doc/6/controllers/ms/sunionstore/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: sunionstore +--- + +# sunionstore + +Computes the union of multiple sets of unique values and stores it in a new set. + +If the destination key already exists, it is overwritten. + +[[_Redis documentation_]](https://redis.io/commands/sunionstore) + +## Arguments + +```js +sunionstore(dest, sources, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `key` | 
string
| Union target key | +| `sources` | 
string[]
| List of set keys | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of values added to the destination key. + +## Usage + +<<< ./snippets/sunionstore.js diff --git a/doc/6/controllers/ms/sunionstore/snippets/sunionstore.js b/doc/6/controllers/ms/sunionstore/snippets/sunionstore.js new file mode 100644 index 000000000..59f60e382 --- /dev/null +++ b/doc/6/controllers/ms/sunionstore/snippets/sunionstore.js @@ -0,0 +1,16 @@ +try { + await kuzzle.ms.sadd('set1', ['a', 'b', 'c']); + await kuzzle.ms.sadd('set2', ['d', 'e', 'f']); + await kuzzle.ms.sadd('set3', ['g', 'h', 'i']); + + // Prints: 9 + console.log(await kuzzle.ms.sunionstore( + 'setdest', + ['set1', 'set2', 'set3'] + )); + + // Prints: [ 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i' ] + console.log(await kuzzle.ms.smembers('setdest')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/sunionstore/snippets/sunionstore.test.yml b/doc/6/controllers/ms/sunionstore/snippets/sunionstore.test.yml new file mode 100644 index 000000000..9f42d0202 --- /dev/null +++ b/doc/6/controllers/ms/sunionstore/snippets/sunionstore.test.yml @@ -0,0 +1,11 @@ +name: ms#sunionstore +description: Stores the union of multiple sets of unique values +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^9$ + - "\\[ ('[a-i]', ){8}'[a-i]' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/time/index.md b/doc/6/controllers/ms/time/index.md new file mode 100644 index 000000000..e3ec5552d --- /dev/null +++ b/doc/6/controllers/ms/time/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: time +--- + +# time + +Returns the current server time. + +[[_Redis documentation_]](https://redis.io/commands/time) + +## Arguments + +```js +time([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the time as a two items array: + +- a timestamp in [Epoch time](https://en.wikipedia.org/wiki/Unix_time) +- the number of microseconds already elapsed in the current second + +## Usage + +<<< ./snippets/time.js diff --git a/doc/6/controllers/ms/time/snippets/time.js b/doc/6/controllers/ms/time/snippets/time.js new file mode 100644 index 000000000..9c8fe916f --- /dev/null +++ b/doc/6/controllers/ms/time/snippets/time.js @@ -0,0 +1,8 @@ +try { + // Prints: [ 1542890183, 868983 ] + // ...but only if the current time on your server is: + // [GMT] Nov. 22, 2018 12:36:23 PM + console.log(await kuzzle.ms.time()); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/time/snippets/time.test.yml b/doc/6/controllers/ms/time/snippets/time.test.yml new file mode 100644 index 000000000..3f1a9b33b --- /dev/null +++ b/doc/6/controllers/ms/time/snippets/time.test.yml @@ -0,0 +1,10 @@ +name: ms#time +description: Returns the current server time +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ \\d{10}, \\d+ ]$" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/touch/index.md b/doc/6/controllers/ms/touch/index.md new file mode 100644 index 000000000..da004fb23 --- /dev/null +++ b/doc/6/controllers/ms/touch/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: touch +--- + +# touch + +Alters the last access time of the provided keys. A key is ignored if it does not exist. + +[[_Redis documentation_]](https://redis.io/commands/touch) + +## Arguments + +```js +touch(keys, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `keys` | 
string[]
| List of keys to alter | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of altered keys. + +## Usage + +<<< ./snippets/touch.js diff --git a/doc/6/controllers/ms/touch/snippets/touch.js b/doc/6/controllers/ms/touch/snippets/touch.js new file mode 100644 index 000000000..a834a7c45 --- /dev/null +++ b/doc/6/controllers/ms/touch/snippets/touch.js @@ -0,0 +1,9 @@ +try { + await kuzzle.ms.set('foo', 'bar'); + await kuzzle.ms.set('baz', 'qux'); + + // Prints: 2 + console.log(await kuzzle.ms.touch(['foo', 'baz', 'thedroidsIamlookingfor'])); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/touch/snippets/touch.test.yml b/doc/6/controllers/ms/touch/snippets/touch.test.yml new file mode 100644 index 000000000..8da644f65 --- /dev/null +++ b/doc/6/controllers/ms/touch/snippets/touch.test.yml @@ -0,0 +1,9 @@ +name: ms#touch +description: Alters the last access time of the provided keys +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^2$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/ttl/index.md b/doc/6/controllers/ms/ttl/index.md new file mode 100644 index 000000000..d9340adeb --- /dev/null +++ b/doc/6/controllers/ms/ttl/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: ttl +--- + +# ttl + +Returns the remaining time to live of a key, in seconds. + +[[_Redis documentation_]](https://redis.io/commands/ttl) + +## Arguments + +```js +ttl(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the remaining key TTL, in seconds, or to a negative value if the key does not exist or if it is persistent. + +## Usage + +<<< ./snippets/ttl.js diff --git a/doc/6/controllers/ms/ttl/snippets/ttl.js b/doc/6/controllers/ms/ttl/snippets/ttl.js new file mode 100644 index 000000000..d5253719e --- /dev/null +++ b/doc/6/controllers/ms/ttl/snippets/ttl.js @@ -0,0 +1,8 @@ +try { + await kuzzle.ms.set('foo', 'bar', {ex: 60}); + + // Prints: 60 + console.log(await kuzzle.ms.ttl('foo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/ttl/snippets/ttl.test.yml b/doc/6/controllers/ms/ttl/snippets/ttl.test.yml new file mode 100644 index 000000000..0b6ac875b --- /dev/null +++ b/doc/6/controllers/ms/ttl/snippets/ttl.test.yml @@ -0,0 +1,9 @@ +name: ms#ttl +description: Returns the remaining time to live of a key, in seconds +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^\d{1,2}$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/type/index.md b/doc/6/controllers/ms/type/index.md new file mode 100644 index 000000000..c055f6eac --- /dev/null +++ b/doc/6/controllers/ms/type/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: type +--- + +# type + +Returns the type of the value held by a key. + +[[_Redis documentation_]](https://redis.io/commands/type) + +## Arguments + +```js +type(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to one of the following: `hash`, `list`, `string`, `set`, `zset` + +## Usage + +<<< ./snippets/type.js diff --git a/doc/6/controllers/ms/type/snippets/type.js b/doc/6/controllers/ms/type/snippets/type.js new file mode 100644 index 000000000..a19c9f25f --- /dev/null +++ b/doc/6/controllers/ms/type/snippets/type.js @@ -0,0 +1,16 @@ +try { + await kuzzle.ms.set('foo', 123); + await kuzzle.ms.rpush('listfoo', ['foo', 'bar', 'baz']); + await kuzzle.ms.sadd('setfoo', ['foo', 'bar', 'baz']); + + // Prints: string + console.log(await kuzzle.ms.type('foo')); + + // Prints: list + console.log(await kuzzle.ms.type('listfoo')); + + // Prints: set + console.log(await kuzzle.ms.type('setfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/type/snippets/type.test.yml b/doc/6/controllers/ms/type/snippets/type.test.yml new file mode 100644 index 000000000..cb36f7b49 --- /dev/null +++ b/doc/6/controllers/ms/type/snippets/type.test.yml @@ -0,0 +1,12 @@ +name: ms#type +description: Returns the type of the value held by a key +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^string$ + - ^list$ + - ^set$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zadd/index.md b/doc/6/controllers/ms/zadd/index.md new file mode 100644 index 000000000..58bad292e --- /dev/null +++ b/doc/6/controllers/ms/zadd/index.md @@ -0,0 +1,60 @@ +--- +code: true +type: page +title: zadd +--- + +# zadd + +Adds elements to a sorted set. + +If the key does not exist, it is created, holding an empty sorted set. + +If the key already exists but does not hold a sorted set, an error is returned. + +If a member to insert is already in the sorted set, its score is updated and the member is reinserted at the right position in the set. + +[[_Redis documentation_]](https://redis.io/commands/zadd) + +## Arguments + +```js +zadd(key, elements, [options]); +``` + +
+ +| Arguments | Type | Description | +| ---------- | ------------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `elements` | 
object[]
| Elements to add | +| `options` | 
object
| Optional query arguments | + +### elements + +The `elements` array lists the elements to add to the sorted set. Each element object has the following properties: + +| Properties | Type | Description | +| ---------- | ----------------- | ------------ | +| `member` | 
string
| Member value | +| `score` | 
string
| Member score | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `ch` | 
boolean (false)
| If true, instead of returning the number of added elements, returns the number of changes performed | +| `incr` | 
boolean (false)
| If true, instead of adding elements, increments the existing member with the provided `score`. Only one element can be specified if this option is set | +| `nx` | 
boolean (false)
| If true, only adds new elements, without altering existing ones | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | +| `xx` | 
boolean (false)
| If true, ignores new elements, alters only existing ones | + +## Resolve + +Resolves to the number of added elements or, if the `ch` option is set, resolves to the number of changes performed. + +## Usage + +<<< ./snippets/zadd.js diff --git a/doc/6/controllers/ms/zadd/snippets/zadd.js b/doc/6/controllers/ms/zadd/snippets/zadd.js new file mode 100644 index 000000000..49d1b24ea --- /dev/null +++ b/doc/6/controllers/ms/zadd/snippets/zadd.js @@ -0,0 +1,15 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: + // [ { member: 'baz', score: -272.15 }, + // { member: 'bar', score: 4 }, + // { member: 'foo', score: 42 } ] + console.log(await kuzzle.ms.zrange('ssetfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zadd/snippets/zadd.test.yml b/doc/6/controllers/ms/zadd/snippets/zadd.test.yml new file mode 100644 index 000000000..688ccce02 --- /dev/null +++ b/doc/6/controllers/ms/zadd/snippets/zadd.test.yml @@ -0,0 +1,12 @@ +name: ms#zadd +description: Adds elements to a sorted set +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { member: 'baz', score: -272.15 }," + - " { member: 'bar', score: 4 }," + - " { member: 'foo', score: 42 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zcard/index.md b/doc/6/controllers/ms/zcard/index.md new file mode 100644 index 000000000..ad9afa03d --- /dev/null +++ b/doc/6/controllers/ms/zcard/index.md @@ -0,0 +1,40 @@ +--- +code: true +type: page +title: zcard +--- + +# zcard + +Returns the number of elements held by a sorted set. + +[[_Redis documentation_]](https://redis.io/commands/zcard) + +## Arguments + +```js +zcard(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of elements in the sorted set. + +## Usage + +<<< ./snippets/zcard.js diff --git a/doc/6/controllers/ms/zcard/snippets/zcard.js b/doc/6/controllers/ms/zcard/snippets/zcard.js new file mode 100644 index 000000000..34b296ab9 --- /dev/null +++ b/doc/6/controllers/ms/zcard/snippets/zcard.js @@ -0,0 +1,12 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints 3 + console.log(await kuzzle.ms.zcard('ssetfoo')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zcard/snippets/zcard.test.yml b/doc/6/controllers/ms/zcard/snippets/zcard.test.yml new file mode 100644 index 000000000..3879d59ef --- /dev/null +++ b/doc/6/controllers/ms/zcard/snippets/zcard.test.yml @@ -0,0 +1,9 @@ +name: ms#zcard +description: Returns the number of elements held by a sorted set +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^3$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zcount/index.md b/doc/6/controllers/ms/zcount/index.md new file mode 100644 index 000000000..388156a2d --- /dev/null +++ b/doc/6/controllers/ms/zcount/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: zcount +--- + +# zcount + +Returns the number of elements held by a sorted set with a score within the provided range. + +[[_Redis documentation_]](https://redis.io/commands/zcount) + +## Arguments + +```js +zcount(key, min, max, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `min` | 
string
| Minimum range value | +| `max` | 
string
| Maximum range value | +| `options` | 
object
| Optional query arguments | + +By default, the provided min and max values are inclusive. This behavior can be changed using the syntax described in the Redis [ZRANGEBYSCORE](https://redis.io/commands/zrangebyscore#exclusive-intervals-and-infinity) documentation. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +## Usage + +<<< ./snippets/zcount.js diff --git a/doc/6/controllers/ms/zcount/snippets/zcount.js b/doc/6/controllers/ms/zcount/snippets/zcount.js new file mode 100644 index 000000000..72b60f2ec --- /dev/null +++ b/doc/6/controllers/ms/zcount/snippets/zcount.js @@ -0,0 +1,13 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: 2 + // Counts elements with a score lower than 42 (excluded) + console.log(await kuzzle.ms.zcount('ssetfoo', '-inf', '(42')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zcount/snippets/zcount.test.yml b/doc/6/controllers/ms/zcount/snippets/zcount.test.yml new file mode 100644 index 000000000..f0e2cc704 --- /dev/null +++ b/doc/6/controllers/ms/zcount/snippets/zcount.test.yml @@ -0,0 +1,9 @@ +name: ms#zcount +description: Counts elements in a sorted set within a score range +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^2$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zincrby/index.md b/doc/6/controllers/ms/zincrby/index.md new file mode 100644 index 000000000..53e502d86 --- /dev/null +++ b/doc/6/controllers/ms/zincrby/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: zincrby +--- + +# zincrby + +Increments the score of a sorted set member by the provided value. + +[[_Redis documentation_]](https://redis.io/commands/zincrby) + +## Arguments + +```js +zincrby(key, member, increment, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------ | ---------------------------------------- | +| `key` | 
string
| Sorted set key | +| `member` | 
string
| Member value | +| `increment` | 
integer
| Increment to apply to the member's score | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the updated member's score. + +## Usage + +<<< ./snippets/zincrby.js diff --git a/doc/6/controllers/ms/zincrby/snippets/zincrby.js b/doc/6/controllers/ms/zincrby/snippets/zincrby.js new file mode 100644 index 000000000..2b6008aee --- /dev/null +++ b/doc/6/controllers/ms/zincrby/snippets/zincrby.js @@ -0,0 +1,17 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + await kuzzle.ms.zincrby('ssetfoo', 'bar', 1333); + + // Prints: + // [ { member: 'baz', score: -272.15 }, + // { member: 'foo', score: 42 }, + // { member: 'bar', score: 1337 } ] + console.log(await kuzzle.ms.zrange('ssetfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zincrby/snippets/zincrby.test.yml b/doc/6/controllers/ms/zincrby/snippets/zincrby.test.yml new file mode 100644 index 000000000..0d968a143 --- /dev/null +++ b/doc/6/controllers/ms/zincrby/snippets/zincrby.test.yml @@ -0,0 +1,12 @@ +name: ms#zincrby +description: Increments the score of a sorted set member by the provided value +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { member: 'baz', score: -272.15 }," + - "\\{ member: 'foo', score: 42 }," + - "\\{ member: 'bar', score: 1337 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zinterstore/index.md b/doc/6/controllers/ms/zinterstore/index.md new file mode 100644 index 000000000..800e26f73 --- /dev/null +++ b/doc/6/controllers/ms/zinterstore/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: zinterstore +--- + +# zinterstore + +Computes the intersection of the provided sorted sets, and stores the result in a new sorted set. + +[[_Redis documentation_]](https://redis.io/commands/zinterstore) + +## Arguments + +```js +zinterstore(dest, sources, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------------------ | +| `dest` | 
string
| Target sorted set key | +| `sources` | 
string[]
| List of sorted set keys to intersect | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `aggregate` | 
string ("sum")
| Specifies how members' scores are aggregated during the intersection.
Allowed values: `min`, `max`, `sum` | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | +| `weights` | 
integer[]
| List of multiplication factors to apply to sources sets, before aggregation. | + +## Resolve + +Resolves to the number of members added to the destination sorted set. + +## Usage + +<<< ./snippets/zinterstore.js diff --git a/doc/6/controllers/ms/zinterstore/snippets/zinterstore.js b/doc/6/controllers/ms/zinterstore/snippets/zinterstore.js new file mode 100644 index 000000000..791344201 --- /dev/null +++ b/doc/6/controllers/ms/zinterstore/snippets/zinterstore.js @@ -0,0 +1,34 @@ +try { + await kuzzle.ms.zadd('sset1', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + await kuzzle.ms.zadd('sset2', [ + {member: 'foo', score: '-29'}, + {member: 'baz', score: '300'} + ]); + + // Sums scores of intersected values + await kuzzle.ms.zinterstore('destsum', ['sset1', 'sset2']); + + // Stores the minimum possible scores of intersected values + await kuzzle.ms.zinterstore( + 'destmin', + ['sset1', 'sset2'], + {aggregate: 'min'} + ); + + // Prints: + // [ { member: 'foo', score: 13 }, + // { member: 'baz', score: 27.85 } ] + console.log(await kuzzle.ms.zrange('destsum', 0, -1)); + + // Prints: + // [ { member: 'baz', score: -272.15 }, + // { member: 'foo', score: -29 } ] + console.log(await kuzzle.ms.zrange('destmin', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zinterstore/snippets/zinterstore.test.yml b/doc/6/controllers/ms/zinterstore/snippets/zinterstore.test.yml new file mode 100644 index 000000000..6ac996ae8 --- /dev/null +++ b/doc/6/controllers/ms/zinterstore/snippets/zinterstore.test.yml @@ -0,0 +1,13 @@ +name: ms#zinterstore +description: Stores the intersection of the provided sorted sets +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { member: 'foo', score: 13 }," + - " { member: 'baz', score: 27.85\\d* } ]" + - "\\[ { member: 'baz', score: -272.15 }" + - " { member: 'foo', score: -29 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zlexcount/index.md b/doc/6/controllers/ms/zlexcount/index.md new file mode 100644 index 000000000..a3e3a8cf2 --- /dev/null +++ b/doc/6/controllers/ms/zlexcount/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: zlexcount +--- + +# zlexcount + +Counts elements in a sorted set where all members have equal score, using lexicographical ordering. + +[[_Redis documentation_]](https://redis.io/commands/zlexcount) + +## Arguments + +```js +zlexcount(key, min, max, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `min` | 
string
| Minimum range value | +| `max` | 
string
| Maximum range value | +| `options` | 
object
| Optional query arguments | + +By default, the provided min and max values are inclusive. This behavior can be changed using the syntax described in the Redis [ZRANGEBYLEX](https://redis.io/commands/zrangebylex#how-to-specify-intervals) documentation. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of elements in the provided range. + +## Usage + +<<< ./snippets/zlexcount.js diff --git a/doc/6/controllers/ms/zlexcount/snippets/zlexcount.js b/doc/6/controllers/ms/zlexcount/snippets/zlexcount.js new file mode 100644 index 000000000..0be03e8eb --- /dev/null +++ b/doc/6/controllers/ms/zlexcount/snippets/zlexcount.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '0'}, + {member: 'bar', score: '0'}, + {member: 'baz', score: '0'} + ]); + + // Prints: 2 + // Lexicographically counts elements with a maximum value of 'f' (excluded), + // without a minimum value + console.log(await kuzzle.ms.zlexcount('ssetfoo', '-', '(f')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zlexcount/snippets/zlexcount.test.yml b/doc/6/controllers/ms/zlexcount/snippets/zlexcount.test.yml new file mode 100644 index 000000000..d6e40d7c6 --- /dev/null +++ b/doc/6/controllers/ms/zlexcount/snippets/zlexcount.test.yml @@ -0,0 +1,9 @@ +name: ms#zlexcount +description: Counts elements in a sorted set using lexicographical ordering +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: ^2$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zrange/index.md b/doc/6/controllers/ms/zrange/index.md new file mode 100644 index 000000000..b0f3d3d75 --- /dev/null +++ b/doc/6/controllers/ms/zrange/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: zrange +--- + +# zrange + +Returns elements depending on their position in the sorted set. + +[[_Redis documentation_]](https://redis.io/commands/zrange) + +## Arguments + +```js +zrange(key, start, stop, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | --------------------------------- | +| `key` | 
string
| Sorted set key | +| `start` | 
integer
| Starting index offset (inclusive) | +| `stop` | 
integer
| Ending index offset (inclusive) | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a list of element objects. + +## Usage + +<<< ./snippets/zrange.js diff --git a/doc/6/controllers/ms/zrange/snippets/zrange.js b/doc/6/controllers/ms/zrange/snippets/zrange.js new file mode 100644 index 000000000..e76070db7 --- /dev/null +++ b/doc/6/controllers/ms/zrange/snippets/zrange.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: + // [ { member: 'baz', score: -272.15 }, + // { member: 'bar', score: 4 } ] + console.log(await kuzzle.ms.zrange('ssetfoo', 0, 1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zrange/snippets/zrange.test.yml b/doc/6/controllers/ms/zrange/snippets/zrange.test.yml new file mode 100644 index 000000000..ad7b75181 --- /dev/null +++ b/doc/6/controllers/ms/zrange/snippets/zrange.test.yml @@ -0,0 +1,11 @@ +name: ms#zrange +description: Returns elements depending on their position in the sorted set +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { member: 'baz', score: -272.15 }," + - "{ member: 'bar', score: 4 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zrangebylex/index.md b/doc/6/controllers/ms/zrangebylex/index.md new file mode 100644 index 000000000..d33aa47c7 --- /dev/null +++ b/doc/6/controllers/ms/zrangebylex/index.md @@ -0,0 +1,45 @@ +--- +code: true +type: page +title: zrangebylex +--- + +# zrangebylex + +Returns elements within a provided interval, in a sorted set where all members have equal score, using lexicographical ordering. + +[[_Redis documentation_]](https://redis.io/commands/zrangebylex) + +## Arguments + +```js +zrangebylex(key, min, max, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `min` | 
string
| Minimum range value | +| `max` | 
string
| Maximum range value | +| `options` | 
object
| Optional query arguments | + +By default, the provided min and max values are inclusive. This behavior can be changed using the syntax described in the Redis [ZRANGEBYLEX](https://redis.io/commands/zrangebylex#how-to-specify-intervals) documentation. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `limit` | 
integer[2]
| An array of 2 integers, used to limit the number of returned matching elements (similar to _SELECT LIMIT offset, count_ in SQL).
Format: `[,]` | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an array of matched elements. + +## Usage + +<<< ./snippets/zrangebylex.js diff --git a/doc/6/controllers/ms/zrangebylex/snippets/zrangebylex.js b/doc/6/controllers/ms/zrangebylex/snippets/zrangebylex.js new file mode 100644 index 000000000..e52f9081b --- /dev/null +++ b/doc/6/controllers/ms/zrangebylex/snippets/zrangebylex.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '0'}, + {member: 'bar', score: '0'}, + {member: 'baz', score: '0'} + ]); + + // Prints: [ 'bar', 'baz' ] + // Lexicographically gets elements with a maximum value of 'f' (excluded), + // without a minimum value + console.log(await kuzzle.ms.zrangebylex('ssetfoo', '-', '(f')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zrangebylex/snippets/zrangebylex.test.yml b/doc/6/controllers/ms/zrangebylex/snippets/zrangebylex.test.yml new file mode 100644 index 000000000..0877b44f6 --- /dev/null +++ b/doc/6/controllers/ms/zrangebylex/snippets/zrangebylex.test.yml @@ -0,0 +1,9 @@ +name: ms#zrangebylex +description: Returns elements within a provided interval, using lexicographical ordering +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'bar', 'baz' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zrangebyscore/index.md b/doc/6/controllers/ms/zrangebyscore/index.md new file mode 100644 index 000000000..4a796e21b --- /dev/null +++ b/doc/6/controllers/ms/zrangebyscore/index.md @@ -0,0 +1,47 @@ +--- +code: true +type: page +title: zrangebyscore +--- + +# zrangebyscore + +Returns all sorted set elements with a score within a provided range. + +The elements are considered to be ordered from low to high scores. + +[[_Redis documentation_]](https://redis.io/commands/zrangebyscore) + +## Arguments + +```js +zrangebyscore(key, min, max, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `min` | 
string
| Minimum score value | +| `max` | 
string
| Maximum score value | +| `options` | 
object
| Optional query arguments | + +By default, `min` and `max` are inclusive. Check the full Redis documentation for other options. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `limit` | 
integer[2]
| An array of 2 integers, used to limit the number of returned matching elements (similar to _SELECT LIMIT offset, count_ in SQL).
Format: `[,]` | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the list of elements in the provided score range. + +## Usage + +<<< ./snippets/zrangebyscore.js diff --git a/doc/6/controllers/ms/zrangebyscore/snippets/zrangebyscore.js b/doc/6/controllers/ms/zrangebyscore/snippets/zrangebyscore.js new file mode 100644 index 000000000..883a68ef5 --- /dev/null +++ b/doc/6/controllers/ms/zrangebyscore/snippets/zrangebyscore.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: + // [ { member: 'baz', score: -272.15 }, + // { member: 'bar', score: 4 } ] + console.log(await kuzzle.ms.zrangebyscore('ssetfoo', '-inf', '(42')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zrangebyscore/snippets/zrangebyscore.test.yml b/doc/6/controllers/ms/zrangebyscore/snippets/zrangebyscore.test.yml new file mode 100644 index 000000000..25e845808 --- /dev/null +++ b/doc/6/controllers/ms/zrangebyscore/snippets/zrangebyscore.test.yml @@ -0,0 +1,11 @@ +name: ms#zrangebyscore +description: Returns all sorted set elements with a score within a provided range +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { member: 'baz', score: -272.15 }," + - "{ member: 'bar', score: 4 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zrank/index.md b/doc/6/controllers/ms/zrank/index.md new file mode 100644 index 000000000..ae68b82de --- /dev/null +++ b/doc/6/controllers/ms/zrank/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: zrank +--- + +# zrank + +Returns the position of an element in a sorted set, with scores sorted in ascending order. The index returned is 0-based (the lowest score member has an index of 0). + +[[_Redis documentation_]](https://redis.io/commands/zrank) + +## Arguments + +```js +zrank(key, member, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `member` | 
string
| Member value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the index of the found member in the sorted set, or to `null` if the member is not found. + +## Usage + +<<< ./snippets/zrank.js diff --git a/doc/6/controllers/ms/zrank/snippets/zrank.js b/doc/6/controllers/ms/zrank/snippets/zrank.js new file mode 100644 index 000000000..f92571cf8 --- /dev/null +++ b/doc/6/controllers/ms/zrank/snippets/zrank.js @@ -0,0 +1,15 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: 2 + console.log(await kuzzle.ms.zrank('ssetfoo', 'foo')); + + // Prints: null + console.log(await kuzzle.ms.zrank('ssetfoo', 'qux')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zrank/snippets/zrank.test.yml b/doc/6/controllers/ms/zrank/snippets/zrank.test.yml new file mode 100644 index 000000000..7c003c8ec --- /dev/null +++ b/doc/6/controllers/ms/zrank/snippets/zrank.test.yml @@ -0,0 +1,11 @@ +name: ms#zrank +description: Returns the position of an element in a sorted set +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^2$ + - ^null$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zrem/index.md b/doc/6/controllers/ms/zrem/index.md new file mode 100644 index 000000000..1778ca68d --- /dev/null +++ b/doc/6/controllers/ms/zrem/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: zrem +--- + +# zrem + +Removes members from a sorted set. + +[[_Redis documentation_]](https://redis.io/commands/zrem) + +## Arguments + +```js +zrem(key, members, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `members` | 
string[]
| Member values to remove | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of removed members. + +## Usage + +<<< ./snippets/zrem.js diff --git a/doc/6/controllers/ms/zrem/snippets/zrem.js b/doc/6/controllers/ms/zrem/snippets/zrem.js new file mode 100644 index 000000000..75893c159 --- /dev/null +++ b/doc/6/controllers/ms/zrem/snippets/zrem.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + await kuzzle.ms.zrem('ssetfoo', ['foo', 'bar']); + + // Prints: [ { member: 'baz', score: -272.15 } ] + console.log(await kuzzle.ms.zrange('ssetfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zrem/snippets/zrem.test.yml b/doc/6/controllers/ms/zrem/snippets/zrem.test.yml new file mode 100644 index 000000000..b3dc91706 --- /dev/null +++ b/doc/6/controllers/ms/zrem/snippets/zrem.test.yml @@ -0,0 +1,9 @@ +name: ms#zrem +description: Removes members from a sorted set +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ { member: 'baz', score: -272.15 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zremrangebylex/index.md b/doc/6/controllers/ms/zremrangebylex/index.md new file mode 100644 index 000000000..e73a28459 --- /dev/null +++ b/doc/6/controllers/ms/zremrangebylex/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: zremrangebylex +--- + +# zremrangebylex + +Removes members within a provided range, from a sorted set where all elements have the same score, using lexicographical ordering. + +[[_Redis documentation_]](https://redis.io/commands/zremrangebylex) + +## Arguments + +```js +zremrangebylex(key, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `min` | 
string
| Minimum range value | +| `max` | 
string
| Maximum range value | +| `options` | 
object
| Optional query arguments | + +By default, the provided min and max values are inclusive. This behavior can be changed using the syntax described in the Redis [ZRANGEBYLEX](https://redis.io/commands/zrangebylex#how-to-specify-intervals) documentation. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of removed members. + +## Usage + +<<< ./snippets/zremrangebylex.js diff --git a/doc/6/controllers/ms/zremrangebylex/snippets/zremrangebylex.js b/doc/6/controllers/ms/zremrangebylex/snippets/zremrangebylex.js new file mode 100644 index 000000000..97fb5a232 --- /dev/null +++ b/doc/6/controllers/ms/zremrangebylex/snippets/zremrangebylex.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '0'}, + {member: 'bar', score: '0'}, + {member: 'baz', score: '0'} + ]); + + await kuzzle.ms.zremrangebylex('ssetfoo', '[baz', '+'); + + // Prints: [ 'bar' ] + console.log(await kuzzle.ms.zrangebylex('ssetfoo', '-', '+')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zremrangebylex/snippets/zremrangebylex.test.yml b/doc/6/controllers/ms/zremrangebylex/snippets/zremrangebylex.test.yml new file mode 100644 index 000000000..a33d40996 --- /dev/null +++ b/doc/6/controllers/ms/zremrangebylex/snippets/zremrangebylex.test.yml @@ -0,0 +1,9 @@ +name: ms#zremrangebylex +description: Removes members within a provided range, using lexicographical ordering +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'bar' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zremrangebyrank/index.md b/doc/6/controllers/ms/zremrangebyrank/index.md new file mode 100644 index 000000000..c2b8b7dad --- /dev/null +++ b/doc/6/controllers/ms/zremrangebyrank/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: zremrangebyrank +--- + +# zremrangebyrank + +Removes members from a sorted set, with their position in the set within a provided index range. + +Positions are 0-based, meaning the first member of the set has a position of 0. + +[[_Redis documentation_]](https://redis.io/commands/zremrangebyrank) + +## Arguments + +```js +zremrangebyrank(key, start, stop, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | --------------------------------- | +| `key` | 
string
| Sorted set key | +| `start` | 
integer
| Starting index offset (inclusive) | +| `stop` | 
integer
| Ending index offset (inclusive) | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of removed elements. + +## Usage + +<<< ./snippets/zremrangebyrank.js diff --git a/doc/6/controllers/ms/zremrangebyrank/snippets/zremrangebyrank.js b/doc/6/controllers/ms/zremrangebyrank/snippets/zremrangebyrank.js new file mode 100644 index 000000000..61c724559 --- /dev/null +++ b/doc/6/controllers/ms/zremrangebyrank/snippets/zremrangebyrank.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + await kuzzle.ms.zremrangebyrank('ssetfoo', 1, 2); + + // Prints: [ { member: 'baz', score: -272.15 } ] + console.log(await kuzzle.ms.zrange('ssetfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zremrangebyrank/snippets/zremrangebyrank.test.yml b/doc/6/controllers/ms/zremrangebyrank/snippets/zremrangebyrank.test.yml new file mode 100644 index 000000000..3dc0390ab --- /dev/null +++ b/doc/6/controllers/ms/zremrangebyrank/snippets/zremrangebyrank.test.yml @@ -0,0 +1,9 @@ +name: ms#zremrangebyrank +description: Removes members from a sorted setn by position +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ { member: 'baz', score: -272.15 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zremrangebyscore/index.md b/doc/6/controllers/ms/zremrangebyscore/index.md new file mode 100644 index 000000000..51f0ef8fd --- /dev/null +++ b/doc/6/controllers/ms/zremrangebyscore/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: zremrangebyscore +--- + +# zremrangebyscore + +Removes members from a sorted set, with a score between the provided interval. + +[[_Redis documentation_]](https://redis.io/commands/zremrangebylex) + +## Arguments + +```js +zremrangebyscore(key, min, max, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `min` | 
string
| Minimum score value | +| `max` | 
string
| Maximum score value | +| `options` | 
object
| Optional query arguments | + +By default, `min` and `max` are inclusive. Check the full Redis documentation for other options. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the number of removed elements. + +## Usage + +<<< ./snippets/zremrangebyscore.js diff --git a/doc/6/controllers/ms/zremrangebyscore/snippets/zremrangebyscore.js b/doc/6/controllers/ms/zremrangebyscore/snippets/zremrangebyscore.js new file mode 100644 index 000000000..3b81af9ba --- /dev/null +++ b/doc/6/controllers/ms/zremrangebyscore/snippets/zremrangebyscore.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + await kuzzle.ms.zremrangebyscore('ssetfoo', '0', '+inf'); + + // Prints: [ { member: 'baz', score: -272.15 } ] + console.log(await kuzzle.ms.zrange('ssetfoo', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zremrangebyscore/snippets/zremrangebyscore.test.yml b/doc/6/controllers/ms/zremrangebyscore/snippets/zremrangebyscore.test.yml new file mode 100644 index 000000000..bd0924e7e --- /dev/null +++ b/doc/6/controllers/ms/zremrangebyscore/snippets/zremrangebyscore.test.yml @@ -0,0 +1,9 @@ +name: ms#zremrangebyscore +description: Removes members from a sorted set, by score +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ { member: 'baz', score: -272.15 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zrevrange/index.md b/doc/6/controllers/ms/zrevrange/index.md new file mode 100644 index 000000000..3c22ff3b2 --- /dev/null +++ b/doc/6/controllers/ms/zrevrange/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: zrevrange +--- + +# zrevrange + +Identical to [zrange](/sdk/js/6/controllers/ms/zrange), except that the sorted set is traversed in descending order. + +[[_Redis documentation_]](https://redis.io/commands/zrevrange) + +## Arguments + +```js +zrevrange(key, start, stop, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | --------------------------------- | +| `key` | 
string
| Sorted set key | +| `start` | 
integer
| Starting index offset (inclusive) | +| `stop` | 
integer
| Ending index offset (inclusive) | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a list of element objects. + +## Usage + +<<< ./snippets/zrevrange.js diff --git a/doc/6/controllers/ms/zrevrange/snippets/zrevrange.js b/doc/6/controllers/ms/zrevrange/snippets/zrevrange.js new file mode 100644 index 000000000..19025699b --- /dev/null +++ b/doc/6/controllers/ms/zrevrange/snippets/zrevrange.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: + // [ { member: 'foo', score: 42 }, + // { member: 'bar', score: 4 } ] + console.log(await kuzzle.ms.zrevrange('ssetfoo', 0, 1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zrevrange/snippets/zrevrange.test.yml b/doc/6/controllers/ms/zrevrange/snippets/zrevrange.test.yml new file mode 100644 index 000000000..a155183b1 --- /dev/null +++ b/doc/6/controllers/ms/zrevrange/snippets/zrevrange.test.yml @@ -0,0 +1,10 @@ +name: ms#zrevrange +description: Returns elements depending on their position in the sorted set, in descending order +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { member: 'foo', score: 42 }, { member: 'bar', score: 4 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zrevrangebylex/index.md b/doc/6/controllers/ms/zrevrangebylex/index.md new file mode 100644 index 000000000..413ac7f97 --- /dev/null +++ b/doc/6/controllers/ms/zrevrangebylex/index.md @@ -0,0 +1,45 @@ +--- +code: true +type: page +title: zrevrangebylex +--- + +# zrevrangebylex + +Identical to [zrangebylex](/core/1/api/controllers/memory-storage/zrangebylex/) except that the sorted set is traversed in descending order. + +[[_Redis documentation_]](https://redis.io/commands/zrevrangebylex) + +## Arguments + +```js +zrevrangebylex(key, min, max, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `min` | 
string
| Minimum range value | +| `max` | 
string
| Maximum range value | +| `options` | 
object
| Optional query arguments | + +By default, the provided min and max values are inclusive. This behavior can be changed using the syntax described in the Redis [ZRANGEBYLEX](https://redis.io/commands/zrangebylex#how-to-specify-intervals) documentation. + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `limit` | 
integer[2]
| An array of 2 integers, used to limit the number of returned matching elements (similar to _SELECT LIMIT offset, count_ in SQL).
Format: `[,]` | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an array of matched elements. + +## Usage + +<<< ./snippets/zrevrangebylex.js diff --git a/doc/6/controllers/ms/zrevrangebylex/snippets/zrevrangebylex.js b/doc/6/controllers/ms/zrevrangebylex/snippets/zrevrangebylex.js new file mode 100644 index 000000000..a056f7261 --- /dev/null +++ b/doc/6/controllers/ms/zrevrangebylex/snippets/zrevrangebylex.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '0'}, + {member: 'bar', score: '0'}, + {member: 'baz', score: '0'} + ]); + + // Prints: [ 'baz', 'bar' ] + // Lexicographically gets elements with a maximum value of 'f' (excluded), + // without a minimum value + console.log(await kuzzle.ms.zrevrangebylex('ssetfoo', '-', '(f')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zrevrangebylex/snippets/zrevrangebylex.test.yml b/doc/6/controllers/ms/zrevrangebylex/snippets/zrevrangebylex.test.yml new file mode 100644 index 000000000..895a059e0 --- /dev/null +++ b/doc/6/controllers/ms/zrevrangebylex/snippets/zrevrangebylex.test.yml @@ -0,0 +1,9 @@ +name: ms#zrevrangebylex +description: Returns elements within a provided interval, using lexicographical ordering +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: "\\[ 'baz', 'bar' ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zrevrangebyscore/index.md b/doc/6/controllers/ms/zrevrangebyscore/index.md new file mode 100644 index 000000000..cf6d3313a --- /dev/null +++ b/doc/6/controllers/ms/zrevrangebyscore/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: zrevrangebyscore +--- + +# zrevrangebyscore + +Identical to [zrangebyscore](/core/1/api/controllers/memory-storage/zrangebyscore/), except that the sorted set is traversed in descending order. + +[[_Redis documentation_]](https://redis.io/commands/zrevrangebyscore) + +## Arguments + +```js +zrevrangebyscore(key, min, max, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `min` | 
string
| Minimum score value | +| `max` | 
string
| Maximum score value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `limit` | 
integer[2]
| An array of 2 integers, used to limit the number of returned matching elements (similar to _SELECT LIMIT offset, count_ in SQL).
Format: `[,]` | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the list of elements in the provided score range, in descending order. + +## Usage + +<<< ./snippets/zrevrangebyscore.js diff --git a/doc/6/controllers/ms/zrevrangebyscore/snippets/zrevrangebyscore.js b/doc/6/controllers/ms/zrevrangebyscore/snippets/zrevrangebyscore.js new file mode 100644 index 000000000..37b591750 --- /dev/null +++ b/doc/6/controllers/ms/zrevrangebyscore/snippets/zrevrangebyscore.js @@ -0,0 +1,14 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: + // [ { member: 'bar', score: 4 }, + // { member: 'baz', score: -272.15 } ] + console.log(await kuzzle.ms.zrevrangebyscore('ssetfoo', '-inf', '(42')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zrevrangebyscore/snippets/zrevrangebyscore.test.yml b/doc/6/controllers/ms/zrevrangebyscore/snippets/zrevrangebyscore.test.yml new file mode 100644 index 000000000..f44188795 --- /dev/null +++ b/doc/6/controllers/ms/zrevrangebyscore/snippets/zrevrangebyscore.test.yml @@ -0,0 +1,12 @@ +name: ms#zrevrangebyscore +description: Returns all sorted set elements with a score within a provided range in descending order +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { member: 'bar', score: 4 }," + - "{ member: 'baz', score: -272.15 } ]" + +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zrevrank/index.md b/doc/6/controllers/ms/zrevrank/index.md new file mode 100644 index 000000000..312aa3a41 --- /dev/null +++ b/doc/6/controllers/ms/zrevrank/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: zrevrank +--- + +# zrevrank + +Returns the position of an element in a sorted set, with scores in descending order. The index returned is 0-based (the lowest score member has an index of 0). + +[[_Redis documentation_]](https://redis.io/commands/zrevrank) + +## Arguments + +```js +zrevrank(key, member, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `member` | 
string
| Member value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the index of the found member in the sorted set, or to `null` if the member is not found. + +## Usage + +<<< ./snippets/zrevrank.js diff --git a/doc/6/controllers/ms/zrevrank/snippets/zrevrank.js b/doc/6/controllers/ms/zrevrank/snippets/zrevrank.js new file mode 100644 index 000000000..9e7442449 --- /dev/null +++ b/doc/6/controllers/ms/zrevrank/snippets/zrevrank.js @@ -0,0 +1,15 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: 0 + console.log(await kuzzle.ms.zrevrank('ssetfoo', 'foo')); + + // Prints: null + console.log(await kuzzle.ms.zrank('ssetfoo', 'qux')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zrevrank/snippets/zrevrank.test.yml b/doc/6/controllers/ms/zrevrank/snippets/zrevrank.test.yml new file mode 100644 index 000000000..7265aa01a --- /dev/null +++ b/doc/6/controllers/ms/zrevrank/snippets/zrevrank.test.yml @@ -0,0 +1,12 @@ +name: ms#zrevrank +description: Returns the position of an element in a sorted set, in reverse order +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^0$ + - ^null$ + +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zscan/index.md b/doc/6/controllers/ms/zscan/index.md new file mode 100644 index 000000000..78be305d6 --- /dev/null +++ b/doc/6/controllers/ms/zscan/index.md @@ -0,0 +1,53 @@ +--- +code: true +type: page +title: zscan +--- + +# zscan + +Iterates incrementally over members contained in a sorted set, using a cursor. + +An iteration starts when the cursor is set to 0. +To get the next page of results, simply re-send the request with the updated cursor position provided in the result set. + +The scan ends when the cursor returned by the server is 0. + +[[_Redis documentation_]](https://redis.io/commands/sscan) + +## Arguments + +```js +zscan(key, cursor, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------ | ------------------------ | +| `key` | 
string
| Sorted set key | +| `cursor` | 
integer
| Cursor offset | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `count` | 
integer (10)
| Return an _approximate_ number of items per result set | +| `match` | 
string (\*)
| Return only keys matching the provided pattern | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an object representing a result page, with the following properties: + +| Property | Type | Description | +| -------- | ------------------- | --------------------------------------------------------------------------------------------------------- | +| `cursor` | 
integer
| Cursor offset for the next page, or `0` if at the end of the scan | +| `values` | 
string[]
| List of member-score pairs. The array entries alternate between member values and their associated scores | + +## Usage + +<<< ./snippets/zscan.js diff --git a/doc/6/controllers/ms/zscan/snippets/zscan.js b/doc/6/controllers/ms/zscan/snippets/zscan.js new file mode 100644 index 000000000..6e8e7304b --- /dev/null +++ b/doc/6/controllers/ms/zscan/snippets/zscan.js @@ -0,0 +1,16 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: + // { + // cursor: '0', + // values: [ 'baz', '-272.15', 'bar', '4', 'foo', '42' ] + // } + console.log(await kuzzle.ms.zscan('ssetfoo', 0)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zscan/snippets/zscan.test.yml b/doc/6/controllers/ms/zscan/snippets/zscan.test.yml new file mode 100644 index 000000000..9a58a6608 --- /dev/null +++ b/doc/6/controllers/ms/zscan/snippets/zscan.test.yml @@ -0,0 +1,11 @@ +name: ms#zscan +description: Iterates incrementally over fields contained in a sorted set, using a cursor +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "{ cursor: '0'," + - "values: \\[ 'baz', '-272.1\\d{1,}', 'bar', '4', 'foo', '42' ] }" +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zscore/index.md b/doc/6/controllers/ms/zscore/index.md new file mode 100644 index 000000000..707d9535f --- /dev/null +++ b/doc/6/controllers/ms/zscore/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: zscore +--- + +# zscore + +Returns the score of an element in a sorted set. + +[[_Redis documentation_]](https://redis.io/commands/zscore) + +## Arguments + +```js +zscore(key, member, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------------------ | +| `key` | 
string
| Sorted set key | +| `member` | 
string
| Member value | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to the member's score. + +## Usage + +<<< ./snippets/zscore.js diff --git a/doc/6/controllers/ms/zscore/snippets/zscore.js b/doc/6/controllers/ms/zscore/snippets/zscore.js new file mode 100644 index 000000000..6826cd3e1 --- /dev/null +++ b/doc/6/controllers/ms/zscore/snippets/zscore.js @@ -0,0 +1,15 @@ +try { + await kuzzle.ms.zadd('ssetfoo', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'}, + {member: 'baz', score: '-272.15'} + ]); + + // Prints: 42 + console.log(await kuzzle.ms.zscore('ssetfoo', 'foo')); + + // Prints: 4 + console.log(await kuzzle.ms.zscore('ssetfoo', 'bar')); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zscore/snippets/zscore.test.yml b/doc/6/controllers/ms/zscore/snippets/zscore.test.yml new file mode 100644 index 000000000..6cb2d2a1d --- /dev/null +++ b/doc/6/controllers/ms/zscore/snippets/zscore.test.yml @@ -0,0 +1,11 @@ +name: ms#zscore +description: Returns the score of an element in a sorted set +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - ^42$ + - ^4$ +sdk: js +version: 6 diff --git a/doc/6/controllers/ms/zunionstore/index.md b/doc/6/controllers/ms/zunionstore/index.md new file mode 100644 index 000000000..fb5e5693c --- /dev/null +++ b/doc/6/controllers/ms/zunionstore/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: zunionstore +--- + +# zunionstore + +Computes the union of the provided sorted sets, and stores the result in a new sorted set. + +[[_Redis documentation_]](https://redis.io/commands/zunionstore) + +## Arguments + +```js +zunionstore(dest, sources, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ------------------- | ------------------------------- | +| `dest` | 
string
| Target sorted set key | +| `sources` | 
string[]
| List of sorted set keys to join | +| `options` | 
object
| Optional query arguments | + +### options + +The `options` arguments can contain the following option properties: + +| Property | Type (default) | Description | +| ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `aggregate` | 
string ("sum")
| Specifies how members' scores are aggregated during the intersection.
Allowed values: `min`, `max`, `sum` | +| `queuable` | 
boolean (true)
| If true, queues the request during downtime, until connected to Kuzzle again | +| `weights` | 
integer[]
| List of multiplication factors to apply to sources sets, before aggregation. | + +## Resolve + +Resolves to the number of members added to the destination sorted set. + +## Usage + +<<< ./snippets/zunionstore.js diff --git a/doc/6/controllers/ms/zunionstore/snippets/zunionstore.js b/doc/6/controllers/ms/zunionstore/snippets/zunionstore.js new file mode 100644 index 000000000..327e9bd2f --- /dev/null +++ b/doc/6/controllers/ms/zunionstore/snippets/zunionstore.js @@ -0,0 +1,35 @@ +try { + await kuzzle.ms.zadd('sset1', [ + {member: 'foo', score: '42'}, + {member: 'bar', score: '4'} + ]); + + await kuzzle.ms.zadd('sset2', [ + {member: 'foo', score: '-29'}, + {member: 'baz', score: '300'} + ]); + + // Sums scores of joined values + await kuzzle.ms.zunionstore('destsum', ['sset1', 'sset2']); + + // Stores the minimum possible scores of joined values + await kuzzle.ms.zunionstore( + 'destmin', + ['sset1', 'sset2'], + {aggregate: 'min'} + ); + + // Prints: + // [ { member: 'bar', score: 4 }, + // { member: 'foo', score: 13 }, + // { member: 'baz', score: 300 } ] + console.log(await kuzzle.ms.zrange('destsum', 0, -1)); + + // Prints: + // [ { member: 'foo', score: -29 }, + // { member: 'bar', score: 4 }, + // { member: 'baz', score: 300 } ] + console.log(await kuzzle.ms.zrange('destmin', 0, -1)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/ms/zunionstore/snippets/zunionstore.test.yml b/doc/6/controllers/ms/zunionstore/snippets/zunionstore.test.yml new file mode 100644 index 000000000..e171869cb --- /dev/null +++ b/doc/6/controllers/ms/zunionstore/snippets/zunionstore.test.yml @@ -0,0 +1,15 @@ +name: ms#zunionstore +description: Stores the union of the provided sorted sets +hooks: + before: curl -X POST kuzzle:7512/ms/_flushdb + after: +template: default +expected: + - "\\[ { member: 'bar', score: 4 }," + - " { member: 'foo', score: 13 }," + - " { member: 'baz', score: 300 } ]" + - "\\[ { member: 'foo', score: -29 }," + - " { member: 'bar', score: 4 }," + - " { member: 'baz', score: 300 } ]" +sdk: js +version: 6 diff --git a/doc/6/controllers/realtime/count/index.md b/doc/6/controllers/realtime/count/index.md new file mode 100644 index 000000000..d8beddf88 --- /dev/null +++ b/doc/6/controllers/realtime/count/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: count +description: Count subscribers for a subscription room +--- + +# count + +Returns the number of other connections sharing the same subscription. + +## Arguments + +```js +count(roomId, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | -------------------- | +| `roomId` | 
string
| Subscription room ID | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Option | Type
(default) | Description | +| ---------- | ------------------------------- | --------------------------------- | +| `queuable` | 
boolean

(`true`) | Make this request queuable or not | + +## Resolves + +Resolves to a number represensting active connections using the same provided subscription room. + +## Usage + +<<< ./snippets/count.js diff --git a/doc/6/controllers/realtime/count/snippets/count.js b/doc/6/controllers/realtime/count/snippets/count.js new file mode 100644 index 000000000..f6f305e57 --- /dev/null +++ b/doc/6/controllers/realtime/count/snippets/count.js @@ -0,0 +1,14 @@ +try { + const roomId = await kuzzle.realtime.subscribe( + 'nyc-open-data', + 'yellow-taxi', + {}, + () => {} + ); + + const count = await kuzzle.realtime.count(roomId); + + console.log(`Currently ${count} active subscription`); +} catch (error) { + console.error(error.message); +} \ No newline at end of file diff --git a/doc/6/controllers/realtime/count/snippets/count.test.yml b/doc/6/controllers/realtime/count/snippets/count.test.yml new file mode 100644 index 000000000..b0ba611a2 --- /dev/null +++ b/doc/6/controllers/realtime/count/snippets/count.test.yml @@ -0,0 +1,10 @@ +name: realtime#count +description: Count subscribers for a subscription room +hooks: + before: + after: +template: default +expected: Currently 1 active subscription + +sdk: js +version: 6 diff --git a/doc/6/controllers/realtime/index.md b/doc/6/controllers/realtime/index.md new file mode 100644 index 000000000..e1753df1d --- /dev/null +++ b/doc/6/controllers/realtime/index.md @@ -0,0 +1,8 @@ +--- +code: true +type: branch +title: realtime +description: Realtime Controller +--- + +# Realtime Controller diff --git a/doc/6/controllers/realtime/publish/index.md b/doc/6/controllers/realtime/publish/index.md new file mode 100644 index 000000000..947c21771 --- /dev/null +++ b/doc/6/controllers/realtime/publish/index.md @@ -0,0 +1,45 @@ +--- +code: true +type: page +title: publish +description: Publish a real-time message +--- + +# publish + +Sends a real-time message to Kuzzle. The message will be dispatched to all clients with subscriptions matching the index, the collection and the message content. + +The index and collection are indicative and serve only to distinguish the rooms. They are not required to exist in the database + +**Note:** real-time messages are not persisted in the database. + +
+ +```js +publish(index, collection, message, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ----------------- | --------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `message` | 
object
| Message to send | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Option | Type
(default) | Description | +| ---------- | ------------------------------- | --------------------------------- | +| `queuable` | 
boolean

(`true`) | Make this request queuable or not | + +## Resolves + +A boolean indicating if the message was successfully published. + +## Usage + +<<< ./snippets/publish.js diff --git a/doc/6/controllers/realtime/publish/snippets/publish.js b/doc/6/controllers/realtime/publish/snippets/publish.js new file mode 100644 index 000000000..854c5ccb0 --- /dev/null +++ b/doc/6/controllers/realtime/publish/snippets/publish.js @@ -0,0 +1,13 @@ +const message = { realtime: 'rule the web' }; + +try { + await kuzzle.realtime.publish( + 'i-dont-exist', + 'in-database', + message + ); + + console.log('Success'); +} catch (error) { + console.error(error.message); +} \ No newline at end of file diff --git a/doc/6/controllers/realtime/publish/snippets/publish.test.yml b/doc/6/controllers/realtime/publish/snippets/publish.test.yml new file mode 100644 index 000000000..b95fffd27 --- /dev/null +++ b/doc/6/controllers/realtime/publish/snippets/publish.test.yml @@ -0,0 +1,10 @@ +name: realtime#publish +description: Publish a realtime message +hooks: + before: + after: +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/realtime/subscribe/index.md b/doc/6/controllers/realtime/subscribe/index.md new file mode 100644 index 000000000..7eb6b6b42 --- /dev/null +++ b/doc/6/controllers/realtime/subscribe/index.md @@ -0,0 +1,64 @@ +--- +code: true +type: page +title: subscribe +description: Subscribe to real-time notifications +--- + +# subscribe + +Subscribes by providing a set of filters: messages, document changes and, optionally, user events matching the provided filters will generate [real-time notifications](/core/1/api/essentials/notifications), sent to you in real-time by Kuzzle. + +
+ +```js +subscribe(index, collection, filters, callback, [options]); +``` + +
+ +| Arguments | Type | Description | +| ------------ | ------------------- | ------------------------------------------------------------- | +| `index` | 
string
| Index name | +| `collection` | 
string
| Collection name | +| `filters` | 
object
| Set of filters following [Koncorde syntax](/core/1/guides/cookbooks/realtime-api/) | +| `callback` | 
function
| Callback function to handle notifications | +| `options` | 
object
| Query options | + +### callback + +Callback function that will be called each time a new notifications is received. +The callback will receive the [notifications object](/sdk/js/6/essentials/realtime-notifications/) as only argument. + +### options + +Additional subscription options. + +| Property | Type
(default) | Description | +| ----------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `scope` | 
string

(`all`) | Subscribe to document entering or leaving the scope
Possible values: `all`, `in`, `out`, `none` | +| `users` | 
string

(`none`) | Subscribe to users entering or leaving the room
Possible values: `all`, `in`, `out`, `none` | +| `subscribeToSelf` | 
boolean

(`true`) | Subscribe to notifications fired by our own queries | +| `volatile` | 
object

(`null`) | subscription information, used in [user join/leave notifications](/core/1/api/essentials/volatile-data/) | + +## Resolves + +Resolves to a string containing the room ID + +## Usage + +_Simple subscription to document notifications_ + +<<< ./snippets/document-notifications.js + +_Subscription to document notifications with scope option_ + +<<< ./snippets/document-notifications-leave-scope.js + +_Subscription to message notifications_ + +<<< ./snippets/message-notifications.js + +_Subscription to user notifications_ + +<<< ./snippets/user-notifications.js diff --git a/doc/6/controllers/realtime/subscribe/snippets/document-notifications-leave-scope.js b/doc/6/controllers/realtime/subscribe/snippets/document-notifications-leave-scope.js new file mode 100644 index 000000000..f0eecc0f1 --- /dev/null +++ b/doc/6/controllers/realtime/subscribe/snippets/document-notifications-leave-scope.js @@ -0,0 +1,48 @@ +function callback (notification) { + console.log(notification); + /* + { status: 200, + requestId: 'e114c5d0-8ad1-4751-9236-772f9fea1b19', + timestamp: 1539783948258, + volatile: { sdkVersion: '6.0.0-beta-2' }, + index: 'nyc-open-data', + collection: 'yellow-taxi', + controller: 'document', + action: 'update', + protocol: 'websocket', + scope: 'out', + state: 'done', + result: { _id: 'AWaCRnfbiSV6vMG7iV_K' }, + type: 'document', + room: '638dd7b94b86720e6ac3f0617f26f116-ae85604010d1f5c7' } + */ + console.log(`Document moved ${notification.scope} from the scope`); +} + +try { + // Subscribe to notifications when document leaves the scope + const filters = { range: { age: { lte: 20 } } }; + const options = { scope: 'out' }; + + await kuzzle.realtime.subscribe( + 'nyc-open-data', + 'yellow-taxi', + filters, + callback, + options + ); + + const document = { name: 'nina vkote', age: 19 }; + + // The document is in the scope + const { _id } = await kuzzle.document.create( + 'nyc-open-data', + 'yellow-taxi', + document + ); + + // The document isn't in the scope anymore + await kuzzle.document.update('nyc-open-data', 'yellow-taxi', _id, { age: 42 }); +} catch (error) { + console.log(error.message); +} diff --git a/doc/6/controllers/realtime/subscribe/snippets/document-notifications-leave-scope.test.yml b/doc/6/controllers/realtime/subscribe/snippets/document-notifications-leave-scope.test.yml new file mode 100644 index 000000000..f4321c129 --- /dev/null +++ b/doc/6/controllers/realtime/subscribe/snippets/document-notifications-leave-scope.test.yml @@ -0,0 +1,10 @@ +name: realtime#subscribe-documents-leave-scope +description: Subscribe to documents leaving the scope +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create ; curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi/ + after: +template: realtime +expected: Document moved out from the scope + +sdk: js +version: 6 diff --git a/doc/6/controllers/realtime/subscribe/snippets/document-notifications.js b/doc/6/controllers/realtime/subscribe/snippets/document-notifications.js new file mode 100644 index 000000000..10e4c4231 --- /dev/null +++ b/doc/6/controllers/realtime/subscribe/snippets/document-notifications.js @@ -0,0 +1,46 @@ +function callback (notification) { + console.log(notification); + /* + { status: 200, + requestId: '1850b835-d82d-4bce-abec-bf593a578763', + timestamp: 1539680191720, + volatile: { sdkVersion: '6.0.0-beta-2' }, + index: 'nyc-open-data', + collection: 'yellow-taxi', + controller: 'document', + action: 'create', + protocol: 'websocket', + scope: 'in', + result: + { _source: + { name: 'nina vkote', + age: 19, + _kuzzle_info: + { author: '-1', + createdAt: 1539680191720, + updatedAt: null, + updater: null, + active: true, + deletedAt: null } }, + _id: 'AWZ8F0TpJD41ulNI_b-v' }, + type: 'document', + room: '14b675feccf5ac320456ef0dbdf6c1fa-7a90af8c8bdaac1b' } + */ + if (notification.scope === 'in') { + console.log(`Document ${notification.result._source.name} enter the scope`); + } else { + console.log(`Document ${notification.result._source.name} leave the scope`); + } +} + +try { + // Subscribe to notifications for documents containing a 'name' property + const filters = { exists: 'name' }; + + await kuzzle.realtime.subscribe('nyc-open-data', 'yellow-taxi', filters, callback); + + const document = { name: 'nina vkote', age: 19 }; + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', document); +} catch (error) { + console.log(error.message); +} diff --git a/doc/6/controllers/realtime/subscribe/snippets/document-notifications.test.yml b/doc/6/controllers/realtime/subscribe/snippets/document-notifications.test.yml new file mode 100644 index 000000000..8dde8db25 --- /dev/null +++ b/doc/6/controllers/realtime/subscribe/snippets/document-notifications.test.yml @@ -0,0 +1,10 @@ +name: realtime#subscribe-documents +description: Simple subscribe to document notifications +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create ; curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi/ + after: +template: realtime +expected: Document nina vkote enter the scope + +sdk: js +version: 6 diff --git a/doc/6/controllers/realtime/subscribe/snippets/message-notifications.js b/doc/6/controllers/realtime/subscribe/snippets/message-notifications.js new file mode 100644 index 000000000..677a89c34 --- /dev/null +++ b/doc/6/controllers/realtime/subscribe/snippets/message-notifications.js @@ -0,0 +1,43 @@ +function callback (notification) { + console.log(notification); + /* + { status: 200, + requestId: '212cc14d-3a4e-4f26-9fe8-6ba6c6279f9d', + timestamp: 1539702246068, + volatile: { sdkVersion: '6.0.0-beta-2' }, + index: 'i-dont-exist', + collection: 'in-database', + controller: 'realtime', + action: 'publish', + protocol: 'websocket', + scope: 'in', + state: 'done', + result: + { _source: + { metAt: 'Insane', + hello: 'world', + _kuzzle_info: + { author: '-1', + createdAt: 1539680191720, + updatedAt: null, + updater: null, + active: true, + deletedAt: null } }, + _id: null }, + type: 'document', + room: '24bbb5c44c343167eaf6a023dca8629e-7a90af8c8bdaac1b' } + */ + console.log('Message notification received'); +} + +try { + // Subscribe to a room + await kuzzle.realtime.subscribe('i-dont-exist', 'in-database', {}, callback); + + // Publish a message to this room + const message = { metAt: 'Insane', hello: 'world' }; + + await kuzzle.realtime.publish('i-dont-exist', 'in-database', message); +} catch (error) { + console.log(error.message); +} \ No newline at end of file diff --git a/doc/6/controllers/realtime/subscribe/snippets/message-notifications.test.yml b/doc/6/controllers/realtime/subscribe/snippets/message-notifications.test.yml new file mode 100644 index 000000000..b97305f9c --- /dev/null +++ b/doc/6/controllers/realtime/subscribe/snippets/message-notifications.test.yml @@ -0,0 +1,10 @@ +name: realtime#subscribe-messages +description: Subscribe to message notifications +hooks: + before: + after: +template: realtime +expected: Message notification received + +sdk: js +version: 6 diff --git a/doc/6/controllers/realtime/subscribe/snippets/user-notifications.js b/doc/6/controllers/realtime/subscribe/snippets/user-notifications.js new file mode 100644 index 000000000..2b9cb8900 --- /dev/null +++ b/doc/6/controllers/realtime/subscribe/snippets/user-notifications.js @@ -0,0 +1,42 @@ +function callback (notification) { + if (notification.type === 'user') { + console.log(notification.volatile); + /* + { sdkVersion: '', username: 'nina vkote' }, + */ + console.log(`Currently ${notification.result.count} users in the room`); + } +} + +try { + const filters = { exists: 'name' }; + // Subscribe users notifications + const options = { users: 'all' }; + + await kuzzle.realtime.subscribe( + 'nyc-open-data', + 'yellow-taxi', + filters, + callback, + options + ); + + // Instantiates a second kuzzle client: multiple subscriptions + // made by the same user will not trigger "new user" notifications + const kuzzle2 = new Kuzzle( + new WebSocket('kuzzle') + ); + await kuzzle2.connect(); + + // Subscribe to the same room with the second client + const options2 = { users: 'all', volatile: { username: 'nina vkote' } }; + await kuzzle2.realtime.subscribe( + 'nyc-open-data', + 'yellow-taxi', + filters, + () => {}, + options2 + ); +} catch (error) { + console.log(error.message); +} diff --git a/doc/6/controllers/realtime/subscribe/snippets/user-notifications.test.yml b/doc/6/controllers/realtime/subscribe/snippets/user-notifications.test.yml new file mode 100644 index 000000000..c0290cea0 --- /dev/null +++ b/doc/6/controllers/realtime/subscribe/snippets/user-notifications.test.yml @@ -0,0 +1,9 @@ +name: realtime#subscribe-users +description: Subscribe to users joining or leaving the room +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create ; curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi/ + after: +template: realtime +expected: "username: 'nina vkote'" +sdk: js +version: 6 diff --git a/doc/6/controllers/realtime/unsubscribe/index.md b/doc/6/controllers/realtime/unsubscribe/index.md new file mode 100644 index 000000000..795959c8a --- /dev/null +++ b/doc/6/controllers/realtime/unsubscribe/index.md @@ -0,0 +1,39 @@ +--- +code: true +type: page +title: unsubscribe +description: Removes a subscription +--- + +# unsubscribe + +Removes a subscription. + +
+ +```js +unsubscribe(roomId, [options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | -------------------- | +| `roomId` | 
string
| Subscription room ID | +| `options` | 
object
| Query options | + +### options + +Additional query options + +| Option | Type
(default) | Description | +| ---------- | ---------------------------- | --------------------------------- | +| `queuable` | 
bool

(`true`) | Make this request queuable or not | + +## Resolves + +Resolves if successfuly unsubscribed. + +## Usage + +<<< ./snippets/unsubscribe.js diff --git a/doc/6/controllers/realtime/unsubscribe/snippets/unsubscribe.js b/doc/6/controllers/realtime/unsubscribe/snippets/unsubscribe.js new file mode 100644 index 000000000..d22947501 --- /dev/null +++ b/doc/6/controllers/realtime/unsubscribe/snippets/unsubscribe.js @@ -0,0 +1,14 @@ +try { + const roomId = await kuzzle.realtime.subscribe( + 'nyc-open-data', + 'yellow-taxi', + {}, + () => {} + ); + + await kuzzle.realtime.unsubscribe(roomId); + + console.log('Success'); +} catch (error) { + console.error(error.message); +} \ No newline at end of file diff --git a/doc/6/controllers/realtime/unsubscribe/snippets/unsubscribe.test.yml b/doc/6/controllers/realtime/unsubscribe/snippets/unsubscribe.test.yml new file mode 100644 index 000000000..72124fdf9 --- /dev/null +++ b/doc/6/controllers/realtime/unsubscribe/snippets/unsubscribe.test.yml @@ -0,0 +1,10 @@ +name: realtime#unsubscribe +description: Removes a subscription +hooks: + before: + after: +template: default +expected: Success + +sdk: js +version: 6 diff --git a/doc/6/controllers/server/admin-exists/index.md b/doc/6/controllers/server/admin-exists/index.md new file mode 100644 index 000000000..9c1e84988 --- /dev/null +++ b/doc/6/controllers/server/admin-exists/index.md @@ -0,0 +1,38 @@ +--- +code: true +type: page +title: adminExists +description: Checks that an administrator account exists. +--- + +# adminExists + +Checks that an administrator account exists. + +
+ +```js +adminExists([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### **Options** + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a `boolean` set to `true` if an admin exists and `false` if it does not. + +## Usage + +<<< ./snippets/admin-exists.js diff --git a/doc/6/controllers/server/admin-exists/snippets/admin-exists.js b/doc/6/controllers/server/admin-exists/snippets/admin-exists.js new file mode 100644 index 000000000..c9c63df7b --- /dev/null +++ b/doc/6/controllers/server/admin-exists/snippets/admin-exists.js @@ -0,0 +1,7 @@ +try { + const exists = await kuzzle.server.adminExists(); + + console.log('Admin exists?', exists); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/server/admin-exists/snippets/admin-exists.test.yml b/doc/6/controllers/server/admin-exists/snippets/admin-exists.test.yml new file mode 100644 index 000000000..823029ea2 --- /dev/null +++ b/doc/6/controllers/server/admin-exists/snippets/admin-exists.test.yml @@ -0,0 +1,10 @@ +name: server#adminExists +description: Checks that an administrator account exists. +hooks: + before: + after: +template: default +expected: ^(Admin exists\?) (true|false)$ + +sdk: js +version: 6 diff --git a/doc/6/controllers/server/get-all-stats/index.md b/doc/6/controllers/server/get-all-stats/index.md new file mode 100644 index 000000000..a808d44d5 --- /dev/null +++ b/doc/6/controllers/server/get-all-stats/index.md @@ -0,0 +1,46 @@ +--- +code: true +type: page +title: getAllStats +description: Gets all stored internal statistic snapshots. +--- + +# getAllStats + +Gets all stored internal statistic snapshots. +By default, snapshots are made every 10 seconds and they are stored for 1 hour. + +These statistics include: + +- the number of connected users per protocol (not available for all protocols) +- the number of ongoing requests +- the number of completed requests since the last frame +- the number of failed requests since the last frame + +
+ +```js +getAllStats([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### **Options** + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an `object` containing all stored internal statistic snapshots. + +## Usage + +<<< ./snippets/get-all-stats.js diff --git a/doc/6/controllers/server/get-all-stats/snippets/get-all-stats.js b/doc/6/controllers/server/get-all-stats/snippets/get-all-stats.js new file mode 100644 index 000000000..c8448b610 --- /dev/null +++ b/doc/6/controllers/server/get-all-stats/snippets/get-all-stats.js @@ -0,0 +1,7 @@ +try { + const allStats = await kuzzle.server.getAllStats(); + + console.log('All Kuzzle Stats:', JSON.stringify(allStats)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/server/get-all-stats/snippets/get-all-stats.test.yml b/doc/6/controllers/server/get-all-stats/snippets/get-all-stats.test.yml new file mode 100644 index 000000000..9f3e4c6bf --- /dev/null +++ b/doc/6/controllers/server/get-all-stats/snippets/get-all-stats.test.yml @@ -0,0 +1,10 @@ +name: server#getAllStats +description: Gets all stored internal statistic snapshots. +hooks: + before: + after: +template: default +expected: ^(All Kuzzle Stats:) {"hits":\[({"connections":{.*},"ongoingRequests":{.*},"completedRequests":{}.*},"failedRequests":{.*},"timestamp":[0-9]{13}}(,)*)+\],"total":[0-9]+}$ + +sdk: js +version: 6 diff --git a/doc/6/controllers/server/get-config/index.md b/doc/6/controllers/server/get-config/index.md new file mode 100644 index 000000000..f1820d340 --- /dev/null +++ b/doc/6/controllers/server/get-config/index.md @@ -0,0 +1,42 @@ +--- +code: true +type: page +title: getConfig +description: Returns the current Kuzzle configuration. +--- + +# getConfig + +Returns the current Kuzzle configuration. + +:::warning +This route should only be accessible to administrators, as it might return sensitive information about the backend. +::: + +
+ +```js +getConfig([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### **Options** + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an `object` containing server configuration. + +## Usage + +<<< ./snippets/get-config.js diff --git a/doc/6/controllers/server/get-config/snippets/get-config.js b/doc/6/controllers/server/get-config/snippets/get-config.js new file mode 100644 index 000000000..7a2080fe7 --- /dev/null +++ b/doc/6/controllers/server/get-config/snippets/get-config.js @@ -0,0 +1,7 @@ +try { + const config = await kuzzle.server.getConfig(); + + console.log('Kuzzle Server configuration:', JSON.stringify(config)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/server/get-config/snippets/get-config.test.yml b/doc/6/controllers/server/get-config/snippets/get-config.test.yml new file mode 100644 index 000000000..9d79d6cfa --- /dev/null +++ b/doc/6/controllers/server/get-config/snippets/get-config.test.yml @@ -0,0 +1,10 @@ +name: server#getConfig +description: Returns the current Kuzzle configuration. +hooks: + before: + after: +template: default +expected: ^(Kuzzle Server configuration:) {("dump":{.*}),("limits":{.*}),("plugins":{.*}),("queues":{.*}),("repositories":{.*}),("server":{.*}),("services":{.*}),("stats":{.*}),("validation":{.*}),("_":.*),("internal":{.*}),("version":"[0-9]\.[0-9]\.[0-9]")}$ + +sdk: js +version: 6 diff --git a/doc/6/controllers/server/get-last-stats/index.md b/doc/6/controllers/server/get-last-stats/index.md new file mode 100644 index 000000000..4b2343fc9 --- /dev/null +++ b/doc/6/controllers/server/get-last-stats/index.md @@ -0,0 +1,47 @@ +--- +code: true +type: page +title: getLastStats +description: Returns the most recent statistics snapshot. +--- + +# getLastStats + +Returns the most recent statistics snapshot. + +By default, snapshots are made every 10 seconds and they are stored for 1 hour. + +These statistics include: + +- the number of connected users per protocol (not available for all protocols) +- the number of ongoing requests +- the number of completed requests since the last frame +- the number of failed requests since the last frame + +
+ +```js +getLastStats([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | no | + +### **Options** + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an `object` containing the most recent statistics snapshot. + +## Usage + +<<< ./snippets/get-last-stats.js diff --git a/doc/6/controllers/server/get-last-stats/snippets/get-last-stats.js b/doc/6/controllers/server/get-last-stats/snippets/get-last-stats.js new file mode 100644 index 000000000..1fb9ee1ee --- /dev/null +++ b/doc/6/controllers/server/get-last-stats/snippets/get-last-stats.js @@ -0,0 +1,7 @@ +try { + const lastStat = await kuzzle.server.getLastStats(); + + console.log('Last Kuzzle Stats:', JSON.stringify(lastStat)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/server/get-last-stats/snippets/get-last-stats.test.yml b/doc/6/controllers/server/get-last-stats/snippets/get-last-stats.test.yml new file mode 100644 index 000000000..0e9b5b000 --- /dev/null +++ b/doc/6/controllers/server/get-last-stats/snippets/get-last-stats.test.yml @@ -0,0 +1,10 @@ +name: server#getLastStats +description: Gets all stored internal statistic snapshots. +hooks: + before: + after: +template: default +expected: ^(Last Kuzzle Stats:) {("connections":{.*}),("ongoingRequests":{.*}),("completedRequests":{.*}),("failedRequests":{.*}),("timestamp":[0-9]{13})}$ + +sdk: js +version: 6 diff --git a/doc/6/controllers/server/get-stats/index.md b/doc/6/controllers/server/get-stats/index.md new file mode 100644 index 000000000..d30996d00 --- /dev/null +++ b/doc/6/controllers/server/get-stats/index.md @@ -0,0 +1,48 @@ +--- +code: true +type: page +title: getStats +description: Returns statistics snapshots within a provided timestamp range. +--- + +# getStats + +Returns statistics snapshots within a provided timestamp range. +By default, snapshots are made every 10 seconds and they are stored for 1 hour. + +These statistics include: + +- the number of connected users per protocol (not available for all protocols) +- the number of ongoing requests +- the number of completed requests since the last frame +- the number of failed requests since the last frame + +
+ +```js +getStats(startTime, stopTime, [options]); +``` + +
+ +| Arguments | Type | Description | +| ----------- | ------------------------- | --------------------------------------------------------------- | +| `startTime` | 
number, string
| Begining of statistics frame set (timestamp or datetime format) | +| `stopTime` | 
number, string
| End of statistics frame set (timestamp or datetime format) | +| `options` | 
object
| Query options | + +### **Options** + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an `object` containing statistics snapshots within the provided range. + +## Usage + +<<< ./snippets/get-stats.js diff --git a/doc/6/controllers/server/get-stats/snippets/get-stats.js b/doc/6/controllers/server/get-stats/snippets/get-stats.js new file mode 100644 index 000000000..d3fb33fb8 --- /dev/null +++ b/doc/6/controllers/server/get-stats/snippets/get-stats.js @@ -0,0 +1,7 @@ +try { + const stats = await kuzzle.server.getStats('1234567890101', '1541426610304'); + + console.log('Kuzzle Stats:', JSON.stringify(stats)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/server/get-stats/snippets/get-stats.test.yml b/doc/6/controllers/server/get-stats/snippets/get-stats.test.yml new file mode 100644 index 000000000..80affa74d --- /dev/null +++ b/doc/6/controllers/server/get-stats/snippets/get-stats.test.yml @@ -0,0 +1,10 @@ +name: server#getStats +description: Returns statistics snapshots within a provided timestamp range. +hooks: + before: + after: +template: default +expected: ^(Kuzzle Stats:) {"hits":\[({"connections":{.*},"ongoingRequests":{.*},"completedRequests":{}.*},"failedRequests":{.*},"timestamp":[0-9]{13}}(,)*)*\],"total":[0-9]+}$ + +sdk: js +version: 6 diff --git a/doc/6/controllers/server/index.md b/doc/6/controllers/server/index.md new file mode 100644 index 000000000..8db5d1500 --- /dev/null +++ b/doc/6/controllers/server/index.md @@ -0,0 +1,8 @@ +--- +code: true +type: branch +title: server +description: Server Controller +--- + +# Server Controller diff --git a/doc/6/controllers/server/info/index.md b/doc/6/controllers/server/info/index.md new file mode 100644 index 000000000..182f32649 --- /dev/null +++ b/doc/6/controllers/server/info/index.md @@ -0,0 +1,38 @@ +--- +code: true +type: page +title: info +description: Returns information about Kuzzle server. +--- + +# info + +Returns information about Kuzzle: available API (base + extended), plugins, external services (Redis, Elasticsearch, ...), servers, etc. + +
+ +```js +info([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### **Options** + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to an `object` containing server information. + +## Usage + +<<< ./snippets/info.js diff --git a/doc/6/controllers/server/info/snippets/info.js b/doc/6/controllers/server/info/snippets/info.js new file mode 100644 index 000000000..b59bcbec6 --- /dev/null +++ b/doc/6/controllers/server/info/snippets/info.js @@ -0,0 +1,7 @@ +try { + const serverInfo = await kuzzle.server.info(); + + console.log('Kuzzle Server information:', JSON.stringify(serverInfo)); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/server/info/snippets/info.test.yml b/doc/6/controllers/server/info/snippets/info.test.yml new file mode 100644 index 000000000..f33e1acc7 --- /dev/null +++ b/doc/6/controllers/server/info/snippets/info.test.yml @@ -0,0 +1,9 @@ +name: server##info +description: Retrieves information about Kuzzle plugins and active services. +hooks: + before: + after: +template: default +expected: "^Kuzzle Server information: {\"serverInfo\":{\"kuzzle\":{\"version\":\"[0-9]\\.[0-9]\\.[0-9]\",\"api\":{.*" +sdk: js +version: 6 diff --git a/doc/6/controllers/server/now/index.md b/doc/6/controllers/server/now/index.md new file mode 100644 index 000000000..9a2ad4777 --- /dev/null +++ b/doc/6/controllers/server/now/index.md @@ -0,0 +1,38 @@ +--- +code: true +type: page +title: now +description: Returns the current server timestamp, in Epoch-millis format. +--- + +# now + +Returns the current server timestamp, in Epoch-millis format. + +
+ +```js +now([options]); +``` + +
+ +| Arguments | Type | Description | +| --------- | ----------------- | ------------- | +| `options` | 
object
| Query options | + +### **Options** + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | ---------------------------------------------------------------------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolve + +Resolves to a number representing the current server timestamp in Epoch-millis format. + +## Usage + +<<< ./snippets/now.js diff --git a/doc/6/controllers/server/now/snippets/now.js b/doc/6/controllers/server/now/snippets/now.js new file mode 100644 index 000000000..c1c7665ae --- /dev/null +++ b/doc/6/controllers/server/now/snippets/now.js @@ -0,0 +1,7 @@ +try { + const timestamp = await kuzzle.server.now(); + + console.log('Epoch-millis timestamp:', timestamp); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/controllers/server/now/snippets/now.test.yml b/doc/6/controllers/server/now/snippets/now.test.yml new file mode 100644 index 000000000..342cdd0a3 --- /dev/null +++ b/doc/6/controllers/server/now/snippets/now.test.yml @@ -0,0 +1,10 @@ +name: server#now +description: Fetch the current server timestamp, in Epoch-millis format. +hooks: + before: + after: +template: default +expected: ^(Epoch-millis timestamp:) [0-9]{13}$ + +sdk: js +version: 6 diff --git a/doc/6/core-classes/base-controller/index.md b/doc/6/core-classes/base-controller/index.md new file mode 100644 index 000000000..15b75fbad --- /dev/null +++ b/doc/6/core-classes/base-controller/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: BaseController +description: BaseController object documentation +order: 500 +--- diff --git a/doc/6/core-classes/base-controller/introduction/index.md b/doc/6/core-classes/base-controller/introduction/index.md new file mode 100644 index 000000000..5692b1d71 --- /dev/null +++ b/doc/6/core-classes/base-controller/introduction/index.md @@ -0,0 +1,13 @@ +--- +code: true +type: page +title: Introduction +description: BaseController class +order: 0 +--- + +# BaseController + +Base class for a [custom SDK controller](/sdk/js/6/essentials/extend-sdk/#define-a-custom-sdk-controller). + +Custom SDK controllers have to extend the `BaseController` class to be added with the [Kuzzle.useController](/sdk/js/6/core-classes/kuzzle/use-controller) method. \ No newline at end of file diff --git a/doc/6/core-classes/base-controller/properties/index.md b/doc/6/core-classes/base-controller/properties/index.md new file mode 100644 index 000000000..d12d79117 --- /dev/null +++ b/doc/6/core-classes/base-controller/properties/index.md @@ -0,0 +1,16 @@ +--- +code: true +type: page +title: Properties +description: BaseController Properties +--- + +# Properties + +| Property name | Type | Description | +| -------------------- | -------- | --------------------------------------- | +| `name` | 
string
| Controller name | +| `kuzzle` | [`Kuzzle`](/sdk/js/6/core-classes/kuzzle/constructor) | Kuzzle SDK instance | + +**Note:** + - The `name` property will be injected in the request sent by the [BaseController.query](/sdk/js/6/core-classes/base-controller/query) method if the `controller` property is not set. \ No newline at end of file diff --git a/doc/6/core-classes/base-controller/query/index.md b/doc/6/core-classes/base-controller/query/index.md new file mode 100644 index 000000000..db26f4c75 --- /dev/null +++ b/doc/6/core-classes/base-controller/query/index.md @@ -0,0 +1,55 @@ +--- +code: true +type: page +title: query +description: Wrapper around the Kuzzle.query method +--- + +# query + +Base method used to send queries to a Kuzzle controller, following the [API Documentation](/core/1/api/essentials/connecting-to-kuzzle). + +This method injects the controller name into the the request and forwards it to the original [Kuzzle.query](/sdk/js/6/core-classes/kuzzle/query) method. + +## Arguments + +```js +query (request, [options]); +``` + +
+ +| Argument | Type | Description | +| -------------- | --------- | ------------- | +| `request` | 
object
| API request | +| `options` | 
object
| Optional query options | + +### request + +All properties necessary for the Kuzzle API can be added in the request object. +The following properties are the most common. + +| Property | Type | Description | +| -------------- | --------- | ------------- | +| `action` | 
string
| Action name (required) | +| `controller` | 
string
| Controller name | +| `body` | 
object
| Query body for this action | +| `index` | 
string
| Index name for this action | +| `collection` | 
string
| Collection name for this action | +| `_id` | 
string
| id for this action | +| `volatile` | 
object
| Additional information to send to Kuzzle | + +**Note:** + - If the `controller` property is not set, the controller [name property](/sdk/js/6/core-classes/base-controller/properties) will be used + +### options + +Additional query options + +| Property | Type
(default) | Description | +| -------------- | --------- | ------------- | +| `queuable` | 
boolean

(`true`) | If true, queues the request during downtime, until connected to Kuzzle again | + +## Resolves + +Resolve to the raw Kuzzle API response. See the [API Documentation](/core/1/api/essentials/connecting-to-kuzzle). \ No newline at end of file diff --git a/doc/6/core-classes/index.md b/doc/6/core-classes/index.md new file mode 100644 index 000000000..cb1e2bab9 --- /dev/null +++ b/doc/6/core-classes/index.md @@ -0,0 +1,7 @@ +--- +code: false +type: branch +order: 200 +title: Core Classes +description: Javascript SDK v6.x core classes +--- diff --git a/doc/6/core-classes/kuzzle-error/index.md b/doc/6/core-classes/kuzzle-error/index.md new file mode 100644 index 000000000..5103a1d24 --- /dev/null +++ b/doc/6/core-classes/kuzzle-error/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: KuzzleError +description: KuzzleError object documentation +order: 510 +--- diff --git a/doc/6/core-classes/kuzzle-error/introduction/index.md b/doc/6/core-classes/kuzzle-error/introduction/index.md new file mode 100644 index 000000000..0f86b1a99 --- /dev/null +++ b/doc/6/core-classes/kuzzle-error/introduction/index.md @@ -0,0 +1,13 @@ +--- +code: false +type: page +title: Introduction +description: KuzzleError object +order: 0 +--- + +# KuzzleError + +Inherits from the standard `Error` class. + +The KuzzleError class represents an [error response from Kuzzle API](/core/1/api/essentials/errors/). \ No newline at end of file diff --git a/doc/6/core-classes/kuzzle-error/properties/index.md b/doc/6/core-classes/kuzzle-error/properties/index.md new file mode 100644 index 000000000..1b5655e92 --- /dev/null +++ b/doc/6/core-classes/kuzzle-error/properties/index.md @@ -0,0 +1,16 @@ +--- +code: false +type: page +title: Properties +description: KuzzleError Properties +order: 10 +--- + + +# Properties + +| Property name | Type | Description | +| -------------------- | -------- | --------------------------------------- | +| `message` | 
string
| Error message | +| `status` | 
number
| Error status code | +| `stack` | 
string
| Error stacktrace (only in development mode) | diff --git a/doc/6/core-classes/kuzzle-event-emitter/add-listener/index.md b/doc/6/core-classes/kuzzle-event-emitter/add-listener/index.md new file mode 100644 index 000000000..8d673ae28 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/add-listener/index.md @@ -0,0 +1,32 @@ +--- +code: true +type: page +title: addListener +description: Adds a new listener for an event +--- + +# addListener + +Adds a listener function to the end of the listeners array for an event. +Whenever an event is triggered, listener functions are called in the order they were registered. + +## Arguments + +```js +addListener (eventName, callback); +``` + +
+ +| Argument | Type | Description | +| ---------- | -------- | -------- | +| `eventName` | 
string
| The name of the event | +| `callback` | 
function
| Function to call every time the event is triggered | + +## Return + +The `KuzzleEventEmitter` instance. + +## Usage + +<<< ./snippets/add-listener.js diff --git a/doc/6/core-classes/kuzzle-event-emitter/add-listener/snippets/add-listener.js b/doc/6/core-classes/kuzzle-event-emitter/add-listener/snippets/add-listener.js new file mode 100644 index 000000000..b98d6e0be --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/add-listener/snippets/add-listener.js @@ -0,0 +1,6 @@ +const eventEmitter = new KuzzleEventEmitter(); + +eventEmitter.addListener('myEvent', () => console.log('Caught event "myEvent"!')); + +// Prints: Caught event "myEvent"! +eventEmitter.emit('myEvent'); diff --git a/doc/6/core-classes/kuzzle-event-emitter/add-listener/snippets/add-listener.test.yml b/doc/6/core-classes/kuzzle-event-emitter/add-listener/snippets/add-listener.test.yml new file mode 100644 index 000000000..32d033093 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/add-listener/snippets/add-listener.test.yml @@ -0,0 +1,9 @@ +name: kuzzleEventEmitter#add-listener +description: Adds new listener for the given event +hooks: + before: + after: +template: eventemitter +expected: Caught event "myEvent"! +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle-event-emitter/add-once-listener/index.md b/doc/6/core-classes/kuzzle-event-emitter/add-once-listener/index.md new file mode 100644 index 000000000..290e83a51 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/add-once-listener/index.md @@ -0,0 +1,33 @@ +--- +code: true +type: page +title: addOnceListener +description: Adds a new listener for an event +--- + +# addOnceListener + +Adds a **one-time** listener function to an event. +The next time the event is triggered, this listener is removed and then invoked. +Whenever an event is triggered, listener functions are called in the order they were registered. + +## Arguments + +```js +addOnceListener(eventName, callback); +``` + +
+ +| Argument | Type | Description | +| ----------- | ------------------- | -------------------------------------------- | +| `eventName` | 
string
| The name of the event | +| `callback` | 
function
| Function to call when the event is triggered | + +## Return + +The `KuzzleEventEmitter` instance. + +## Usage + +<<< ./snippets/add-once-listener.js diff --git a/doc/6/core-classes/kuzzle-event-emitter/add-once-listener/snippets/add-once-listener.js b/doc/6/core-classes/kuzzle-event-emitter/add-once-listener/snippets/add-once-listener.js new file mode 100644 index 000000000..2f63326c1 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/add-once-listener/snippets/add-once-listener.js @@ -0,0 +1,11 @@ +const eventEmitter = new KuzzleEventEmitter(); + +eventEmitter.addOnceListener( + 'myEvent', + () => console.log('Caught event "myEvent"!')); + +// Prints: Caught event "myEvent"! +eventEmitter.emit('myEvent'); + +// Prints nothing: the event has since been removed +eventEmitter.emit('myEvent'); diff --git a/doc/6/core-classes/kuzzle-event-emitter/add-once-listener/snippets/add-once-listener.test.yml b/doc/6/core-classes/kuzzle-event-emitter/add-once-listener/snippets/add-once-listener.test.yml new file mode 100644 index 000000000..fe7b777ac --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/add-once-listener/snippets/add-once-listener.test.yml @@ -0,0 +1,9 @@ +name: kuzzleEventEmitter#add-once-listener +description: Adds new once listener for the given event +hooks: + before: + after: +template: eventemitter +expected: Caught event "myEvent"! +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle-event-emitter/emit/index.md b/doc/6/core-classes/kuzzle-event-emitter/emit/index.md new file mode 100644 index 000000000..41b9b4775 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/emit/index.md @@ -0,0 +1,31 @@ +--- +code: true +type: page +title: emit +description: Emits an event +--- + +# emit + +Emits an event with the specified payload. + +## Arguments + +```js +emit(eventName, ...payload); +``` + +
+ +| Argument | Type | Description | +| ----------- | ----------------- | --------------------------------- | +| `eventName` | 
string
| The name of the event | +| `payload` | 
any
| Payload(s) to send with the event | + +## Return + +The `KuzzleEventEmitter` instance. + +## Usage + +<<< ./snippets/emit.js diff --git a/doc/6/core-classes/kuzzle-event-emitter/emit/snippets/emit.js b/doc/6/core-classes/kuzzle-event-emitter/emit/snippets/emit.js new file mode 100644 index 000000000..b70bf929b --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/emit/snippets/emit.js @@ -0,0 +1,5 @@ +const eventEmitter = new KuzzleEventEmitter(); + +eventEmitter.addListener('helloEvent', msg => console.log(`Hello ${msg}`)); + +eventEmitter.emit('helloEvent', 'World'); diff --git a/doc/6/core-classes/kuzzle-event-emitter/emit/snippets/emit.test.yml b/doc/6/core-classes/kuzzle-event-emitter/emit/snippets/emit.test.yml new file mode 100644 index 000000000..e2dec6f61 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/emit/snippets/emit.test.yml @@ -0,0 +1,9 @@ +name: kuzzleEventEmitter#emit +description: Emits an event +hooks: + before: + after: +template: eventemitter +expected: Hello World +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle-event-emitter/index.md b/doc/6/core-classes/kuzzle-event-emitter/index.md new file mode 100644 index 000000000..f7b127318 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: KuzzleEventEmitter +description: KuzzleEventEmitter class documentation +order: 510 +--- diff --git a/doc/6/core-classes/kuzzle-event-emitter/introduction/index.md b/doc/6/core-classes/kuzzle-event-emitter/introduction/index.md new file mode 100644 index 000000000..7e3981199 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/introduction/index.md @@ -0,0 +1,18 @@ +--- +code: false +type: page +title: Introduction +description: KuzzleEventEmitter class +order: 0 +--- + +# KuzzleEventEmitter + +A portable implementation of the Node.js `EventEmitter` interface. + +There are several classes extending `KuzzleEventEmitter` in the SDK: + +- [Kuzzle](/sdk/js/6/core-classes/kuzzle) +- [WebSocket](/sdk/js/6/protocols/websocket) +- [Http](/sdk/js/6/protocols/http) +- [SocketIO](/sdk/js/6/protocols/socketio) diff --git a/doc/6/core-classes/kuzzle-event-emitter/listeners/index.md b/doc/6/core-classes/kuzzle-event-emitter/listeners/index.md new file mode 100644 index 000000000..1455ff4f7 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/listeners/index.md @@ -0,0 +1,24 @@ +--- +code: true +type: page +title: listeners +description: Returns listeners for an event +--- + +# listeners + +Returns the listener functions bound to a specific event. + +## Arguments + +```js +listeners(eventName); +``` + +## Return + +An array of listener functions. + +## Usage + +<<< ./snippets/listeners.js diff --git a/doc/6/core-classes/kuzzle-event-emitter/listeners/snippets/listeners.js b/doc/6/core-classes/kuzzle-event-emitter/listeners/snippets/listeners.js new file mode 100644 index 000000000..4e5e83699 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/listeners/snippets/listeners.js @@ -0,0 +1,8 @@ +const eventEmitter = new KuzzleEventEmitter(); + +eventEmitter.addListener('myEvent', () => console.log('Hello')); +eventEmitter.addListener('myEvent', () => console.log('Hello World')); + +const listeners = eventEmitter.listeners('myEvent'); + +console.log(`There are ${listeners.length} listeners bound to the event "myEvent"`); diff --git a/doc/6/core-classes/kuzzle-event-emitter/listeners/snippets/listeners.test.yml b/doc/6/core-classes/kuzzle-event-emitter/listeners/snippets/listeners.test.yml new file mode 100644 index 000000000..fe978c60d --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/listeners/snippets/listeners.test.yml @@ -0,0 +1,9 @@ +name: kuzzleEventEmitter#listeners +description: Returns listeners binded to an event +hooks: + before: + after: +template: eventemitter +expected: There are 2 listeners bound to the event "myEvent" +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle-event-emitter/on/index.md b/doc/6/core-classes/kuzzle-event-emitter/on/index.md new file mode 100644 index 000000000..2d76aa56c --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/on/index.md @@ -0,0 +1,10 @@ +--- +code: true +type: page +title: on +description: Alias for addListener +--- + +# on + +Alias for [addListener](https://nodejs.org/api/events.html#events_emitter_addlistener_eventname_listener). diff --git a/doc/6/core-classes/kuzzle-event-emitter/once/index.md b/doc/6/core-classes/kuzzle-event-emitter/once/index.md new file mode 100644 index 000000000..ca3e6b4b3 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/once/index.md @@ -0,0 +1,10 @@ +--- +code: true +type: page +title: once +description: Alias for addOnceListener +--- + +# once + +Alias for [addOnceListener](/sdk/js/6/core-classes/kuzzle-event-emitter/add-once-listener/). diff --git a/doc/6/core-classes/kuzzle-event-emitter/prepend-listener/index.md b/doc/6/core-classes/kuzzle-event-emitter/prepend-listener/index.md new file mode 100644 index 000000000..a36187191 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/prepend-listener/index.md @@ -0,0 +1,31 @@ +--- +code: true +type: page +title: prependListener +description: Prepends a new listener for an event +--- + +# prependListener + +Adds a listener function to the beginning of the listeners array for an event. + +## Arguments + +```js +prependListener(eventName, callback); +``` + +
+ +| Argument | Type | Description | +| ----------- | ------------------- | -------------------------------------------------- | +| `eventName` | 
string
| The name of the event | +| `callback` | 
function
| Function to call every time the event is triggered | + +## Return + +The `KuzzleEventEmitter` instance. + +## Usage + +<<< ./snippets/prepend-listener.js diff --git a/doc/6/core-classes/kuzzle-event-emitter/prepend-listener/snippets/prepend-listener.js b/doc/6/core-classes/kuzzle-event-emitter/prepend-listener/snippets/prepend-listener.js new file mode 100644 index 000000000..997536d57 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/prepend-listener/snippets/prepend-listener.js @@ -0,0 +1,10 @@ +const eventEmitter = new KuzzleEventEmitter(); + +eventEmitter.addListener('myEvent', () => console.log('listener1')); + +eventEmitter.prependListener('myEvent', () => console.log('listener2')); + +// Prints: +// listener2 +// listener1 +eventEmitter.emit('myEvent'); diff --git a/doc/6/core-classes/kuzzle-event-emitter/prepend-listener/snippets/prepend-listener.test.yml b/doc/6/core-classes/kuzzle-event-emitter/prepend-listener/snippets/prepend-listener.test.yml new file mode 100644 index 000000000..6bb15910b --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/prepend-listener/snippets/prepend-listener.test.yml @@ -0,0 +1,11 @@ +name: kuzzleEventEmitter#prepend-listener +description: Prepends a new listener for the given event +hooks: + before: + after: +template: eventemitter +expected: + - ^listener2$ + - ^listener1$ +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle-event-emitter/prepend-once-listener/index.md b/doc/6/core-classes/kuzzle-event-emitter/prepend-once-listener/index.md new file mode 100644 index 000000000..216d7af60 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/prepend-once-listener/index.md @@ -0,0 +1,32 @@ +--- +code: true +type: page +title: prependOnceListener +description: Prepends a new once listener for an event +--- + +# prependOnceListener + +Adds a **one-time** listener function for an event to the beginning of the listeners array. +The next time that event is triggered, this listener is removed, and then invoked. + +## Arguments + +```js +prependOnceListener(eventName, callback); +``` + +
+ +| Argument | Type | Description | +| ----------- | ------------------- | -------------------------------------------- | +| `eventName` | 
string
| The name of the event | +| `callback` | 
function
| Function to call when the event is triggered | + +## Return + +The `KuzzleEventEmitter` instance. + +## Usage + +<<< ./snippets/prepend-once-listener.js diff --git a/doc/6/core-classes/kuzzle-event-emitter/prepend-once-listener/snippets/prepend-once-listener.js b/doc/6/core-classes/kuzzle-event-emitter/prepend-once-listener/snippets/prepend-once-listener.js new file mode 100644 index 000000000..479c42e3c --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/prepend-once-listener/snippets/prepend-once-listener.js @@ -0,0 +1,14 @@ +const eventEmitter = new KuzzleEventEmitter(); + +eventEmitter.addListener('myEvent', () => console.log('listener1')); + +eventEmitter.prependOnceListener('myEvent', () => console.log('listener2')); + +// Prints: +// listener2 +// listener1 +eventEmitter.emit('myEvent'); + +// Prints: listener1 +// (the listener function printing "listener2" as since been removed) +eventEmitter.emit('myEvent'); diff --git a/doc/6/core-classes/kuzzle-event-emitter/prepend-once-listener/snippets/prepend-once-listener.test.yml b/doc/6/core-classes/kuzzle-event-emitter/prepend-once-listener/snippets/prepend-once-listener.test.yml new file mode 100644 index 000000000..d329f51ff --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/prepend-once-listener/snippets/prepend-once-listener.test.yml @@ -0,0 +1,12 @@ +name: kuzzleEventEmitter#prepend-once-listener +description: Prepends an once new listener for the given event +hooks: + before: + after: +template: eventemitter +expected: + - ^listener2$ + - ^listener1$ + - ^listener1$ +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle-event-emitter/remove-all-listener/index.md b/doc/6/core-classes/kuzzle-event-emitter/remove-all-listener/index.md new file mode 100644 index 000000000..4f38ff477 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/remove-all-listener/index.md @@ -0,0 +1,31 @@ +--- +code: true +type: page +title: removeAllListeners +description: Removes all listener functions, or all listener functions from an event +--- + +# removeAllListeners + +Removes all listener functions from an event. +If no eventName is specified, removes all listener functions from all events. + +## Arguments + +```js +removeAllListeners([eventName]); +``` + +
+ +| Argument | Type | Description | +| ----------- | ----------------- | -------------------------- | +| `eventName` | 
string
| Optional name of the event | + +## Return + +The `KuzzleEventEmitter` instance. + +## Usage + +<<< ./snippets/remove-all-listeners.js diff --git a/doc/6/core-classes/kuzzle-event-emitter/remove-all-listener/snippets/remove-all-listeners.js b/doc/6/core-classes/kuzzle-event-emitter/remove-all-listener/snippets/remove-all-listeners.js new file mode 100644 index 000000000..00154de84 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/remove-all-listener/snippets/remove-all-listeners.js @@ -0,0 +1,18 @@ +const eventEmitter = new KuzzleEventEmitter(); + +eventEmitter.addListener('myEvent', () => console.log('Caught event "myEvent" (1)')); +eventEmitter.addListener('myEvent', () => console.log('Caught event "myEvent" (2)')); + +// Prints: +// Caught event "myEvent" (1) +// Caught event "myEvent" (2) +eventEmitter.emit('myEvent'); + +eventEmitter.removeAllListeners('myEvent'); + +// Prints nothing: all events have been removed +eventEmitter.emit('myEvent'); + +if (eventEmitter.listeners('myEvent').length === 0) { + console.log('Successfully removed all listeners'); +} diff --git a/doc/6/core-classes/kuzzle-event-emitter/remove-all-listener/snippets/remove-all-listeners.test.yml b/doc/6/core-classes/kuzzle-event-emitter/remove-all-listener/snippets/remove-all-listeners.test.yml new file mode 100644 index 000000000..043d330e0 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/remove-all-listener/snippets/remove-all-listeners.test.yml @@ -0,0 +1,9 @@ +name: kuzzleEventEmitter#remove-all-listeners +description: Removes a listener for the given event +hooks: + before: + after: +template: eventemitter +expected: Successfully removed all listeners +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle-event-emitter/remove-listener/index.md b/doc/6/core-classes/kuzzle-event-emitter/remove-listener/index.md new file mode 100644 index 000000000..7b58fc659 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/remove-listener/index.md @@ -0,0 +1,31 @@ +--- +code: true +type: page +title: removeListener +description: Removes a listener function from an event +--- + +# removeListener + +Removes a listener function from an event. + +## Arguments + +```js +removeListener(eventName, callback); +``` + +
+ +| Argument | Type | Description | +| ----------- | ------------------- | --------------------- | +| `eventName` | 
string
| The name of the event | +| `callback` | 
function
| Callback to remove | + +## Return + +The `KuzzleEventEmitter` instance. + +## Usage + +<<< ./snippets/remove-listener.js diff --git a/doc/6/core-classes/kuzzle-event-emitter/remove-listener/snippets/remove-listener.js b/doc/6/core-classes/kuzzle-event-emitter/remove-listener/snippets/remove-listener.js new file mode 100644 index 000000000..8c7276211 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/remove-listener/snippets/remove-listener.js @@ -0,0 +1,13 @@ +const eventEmitter = new KuzzleEventEmitter(); + +const listener = () => console.log('disconnected'); + +eventEmitter + .addListener('disconnected', () => console.log('disconnected')) + .addListener('disconnected', listener); + +eventEmitter.removeListener('disconnected', listener); + +if (eventEmitter.listeners('disconnected').length === 1) { + console.log('Successfully removed the listener'); +} diff --git a/doc/6/core-classes/kuzzle-event-emitter/remove-listener/snippets/remove-listener.test.yml b/doc/6/core-classes/kuzzle-event-emitter/remove-listener/snippets/remove-listener.test.yml new file mode 100644 index 000000000..d50965568 --- /dev/null +++ b/doc/6/core-classes/kuzzle-event-emitter/remove-listener/snippets/remove-listener.test.yml @@ -0,0 +1,9 @@ +name: kuzzleEventEmitter#remove-listener +description: Removes a listener for the given event +hooks: + before: + after: +template: eventemitter +expected: Successfully removed the listener +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle/connect/index.md b/doc/6/core-classes/kuzzle/connect/index.md new file mode 100644 index 000000000..ec8404a64 --- /dev/null +++ b/doc/6/core-classes/kuzzle/connect/index.md @@ -0,0 +1,25 @@ +--- +code: true +type: page +title: connect +description: Connects the SDK to Kuzzle +--- + +# connect + +Connects to Kuzzle using the `host` property provided in the [constructor options](/sdk/js/6/core-classes/kuzzle/constructor/#arguments). +Subsequent call have no effect if the SDK is already connected. + +## Arguments + +```js +connect(); +``` + +## Resolves + +Resolves if the connection is successful. + +## Usage + +<<< ./snippets/connect.js diff --git a/doc/6/core-classes/kuzzle/connect/snippets/connect.js b/doc/6/core-classes/kuzzle/connect/snippets/connect.js new file mode 100644 index 000000000..6a12ea0c1 --- /dev/null +++ b/doc/6/core-classes/kuzzle/connect/snippets/connect.js @@ -0,0 +1,7 @@ +try { + await kuzzle.connect(); + + console.log('Successfully connected'); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/core-classes/kuzzle/connect/snippets/connect.test.yml b/doc/6/core-classes/kuzzle/connect/snippets/connect.test.yml new file mode 100644 index 000000000..e904c4c4a --- /dev/null +++ b/doc/6/core-classes/kuzzle/connect/snippets/connect.test.yml @@ -0,0 +1,11 @@ +--- +name: kuzzle#connect +description: Connects the SDK to Kuzzle +hooks: + before: + after: +template: without-connect +expected: Successfully connected + +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle/constructor/index.md b/doc/6/core-classes/kuzzle/constructor/index.md new file mode 100644 index 000000000..618fe9828 --- /dev/null +++ b/doc/6/core-classes/kuzzle/constructor/index.md @@ -0,0 +1,58 @@ +--- +code: true +type: page +title: constructor +description: Creates a new Kuzzle object connected to the backend +order: 50 +--- + +# Constructor + +Use this constructor to create a new instance of the SDK. +Each instance represent a different connection to a Kuzzle server with specific options. + +## Arguments + +```js +Kuzzle(protocol, [options]); +``` + +
+ +| Argument | Type | Description | +| ---------- | ------------------- | --------------------------------- | +| `protocol` | 
Protocol
| Protocol used by the SDK instance | +| `options` | 
object
| Kuzzle object configuration | + +### protocol + +The protocol used to connect to the Kuzzle instance. +It can be one of the following available protocols: + +- [WebSocket](/sdk/js/6/protocols/websocket) +- [Http](/sdk/js/6/protocols/http) +- [SocketIO](/sdk/js/6/protocols/socketio) + +### options + +Kuzzle SDK instance options. + +| Property | Type
(default) | Description | +| ----------------- | -------------------------------- | ------------------------------------------------------------------ | +| `autoQueue` | 
boolean

(`false`) | Automatically queue all requests during offline mode | +| `autoReplay` | 
boolean

(`false`) | Automatically replay queued requests on a `reconnected` event | +| `autoResubscribe` | 
boolean

(`true`) | Automatically renew all subscriptions on a `reconnected` event | +| `eventTimeout` | 
number

(`200`) | Time (in ms) during which a similar event is ignored | +| `offlineMode` | 
string

(`manual`) | Offline mode configuration. Can be `manual` or `auto` | +| `queueTTL` | 
number

(`120000`) | Time a queued request is kept during offline mode, in milliseconds | +| `queueMaxSize` | 
number

(`500`) | Number of maximum requests kept during offline mode | +| `replayInterval` | 
number

(`10`) | Delay between each replayed requests, in milliseconds | +| `volatile` | 
object

(`{}`) | Common volatile data, will be sent to all future requests | + +## Return + +The `Kuzzle` SDK instance. + +## Usage + +<<< ./snippets/constructor.js diff --git a/doc/6/core-classes/kuzzle/constructor/snippets/constructor.js b/doc/6/core-classes/kuzzle/constructor/snippets/constructor.js new file mode 100644 index 000000000..f362d01c3 --- /dev/null +++ b/doc/6/core-classes/kuzzle/constructor/snippets/constructor.js @@ -0,0 +1,25 @@ +// Loads the Kuzzle SDK module +const + { + Kuzzle, + WebSocket, + Http + } = require('kuzzle-sdk'); + +const options = { + offlineMode: 'auto', + volatile: { username: 'Gordon' } +}; + +// Instantiates the SDK with the websocket protocol +const + kuzzleWs = new Kuzzle( + new WebSocket('kuzzle'), + options + ); + +// Instantiates the SDK with the http protocol +const + kuzzleHttp = new Kuzzle( + new Http('kuzzle') + ); diff --git a/doc/6/core-classes/kuzzle/constructor/snippets/constructor.test.yml b/doc/6/core-classes/kuzzle/constructor/snippets/constructor.test.yml new file mode 100644 index 000000000..2a43f0463 --- /dev/null +++ b/doc/6/core-classes/kuzzle/constructor/snippets/constructor.test.yml @@ -0,0 +1,10 @@ +--- +name: kuzzle#constructor +description: Creates a new Kuzzle instance connected to kuzzle +hooks: + before: + after: +template: empty +expected: Success +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle/disconnect/index.md b/doc/6/core-classes/kuzzle/disconnect/index.md new file mode 100644 index 000000000..896ab0e0b --- /dev/null +++ b/doc/6/core-classes/kuzzle/disconnect/index.md @@ -0,0 +1,22 @@ +--- +code: true +type: page +title: disconnect +description: Disconnect the SDK +--- + +# disconnect + +Closes the current connection to Kuzzle. +The SDK then enters the `offline` state. +A call to `disconnect()` will not trigger a `disconnected` event. This event is only triggered on unexpected disconnection. + +## Arguments + +```js +disconnect(); +``` + +## Usage + +<<< ./snippets/disconnect.js diff --git a/doc/6/core-classes/kuzzle/disconnect/snippets/disconnect.js b/doc/6/core-classes/kuzzle/disconnect/snippets/disconnect.js new file mode 100644 index 000000000..e3c9244e6 --- /dev/null +++ b/doc/6/core-classes/kuzzle/disconnect/snippets/disconnect.js @@ -0,0 +1,7 @@ +try { + kuzzle.disconnect(); + + console.log('Successfully disconnected'); +} catch (error) { + console.error(error); +} diff --git a/doc/6/core-classes/kuzzle/disconnect/snippets/disconnect.test.yml b/doc/6/core-classes/kuzzle/disconnect/snippets/disconnect.test.yml new file mode 100644 index 000000000..275657be6 --- /dev/null +++ b/doc/6/core-classes/kuzzle/disconnect/snippets/disconnect.test.yml @@ -0,0 +1,11 @@ +--- +name: kuzzle#disconnect +description: Disconnects the SDK +hooks: + before: + after: +template: without-connect +expected: Successfully disconnected + +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle/flush-queue/index.md b/doc/6/core-classes/kuzzle/flush-queue/index.md new file mode 100644 index 000000000..9245cf5f6 --- /dev/null +++ b/doc/6/core-classes/kuzzle/flush-queue/index.md @@ -0,0 +1,24 @@ +--- +code: true +type: page +title: flushQueue +description: Empties the offline request queue +--- + +# flushQueue + +Empties the offline request queue without playing it. + +## Arguments + +```js +flushQueue(); +``` + +## Return + +The `Kuzzle` instance. + +## Usage + +<<< ./snippets/flush-queue.js diff --git a/doc/6/core-classes/kuzzle/flush-queue/snippets/flush-queue.js b/doc/6/core-classes/kuzzle/flush-queue/snippets/flush-queue.js new file mode 100644 index 000000000..1ce69b412 --- /dev/null +++ b/doc/6/core-classes/kuzzle/flush-queue/snippets/flush-queue.js @@ -0,0 +1,7 @@ +try { + kuzzle.flushQueue(); + + console.log('Offline queue flushed'); +} catch (error) { + console.error(error); +} diff --git a/doc/6/core-classes/kuzzle/flush-queue/snippets/flush-queue.test.yml b/doc/6/core-classes/kuzzle/flush-queue/snippets/flush-queue.test.yml new file mode 100644 index 000000000..704e7e084 --- /dev/null +++ b/doc/6/core-classes/kuzzle/flush-queue/snippets/flush-queue.test.yml @@ -0,0 +1,11 @@ +--- +name: kuzzle#flushQueue +description: Empties the offline request queue +hooks: + before: + after: +template: without-connect +expected: Offline queue flushed + +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle/index.md b/doc/6/core-classes/kuzzle/index.md new file mode 100644 index 000000000..81ec30a82 --- /dev/null +++ b/doc/6/core-classes/kuzzle/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: Kuzzle +description: Kuzzle object documentation +order: 510 +--- diff --git a/doc/6/core-classes/kuzzle/introduction/index.md b/doc/6/core-classes/kuzzle/introduction/index.md new file mode 100644 index 000000000..eeb4b1549 --- /dev/null +++ b/doc/6/core-classes/kuzzle/introduction/index.md @@ -0,0 +1,37 @@ +--- +code: false +type: page +title: Introduction +description: Kuzzle object +order: 0 +--- + +# Kuzzle + +Inherits from: [KuzzleEventEmitter](/sdk/js/6/core-classes/kuzzle-event-emitter). + +The Kuzzle class is the main class of the SDK. +Once instantiated, it represents a connection to your Kuzzle server. + +It gives access to the different features of the SDKs: + +- access to the available controllers +- [SDK events](/sdk/cpp/1/essentials/events) handling +- resilience to connection loss +- network request queue management + +## Network protocol + +Each instance of the class communicates with the Kuzzle server through a class representing a network protocol implementation. + +The following protocols are available in the SDK JS 6: + +- [WebSocket](/sdk/js/6/protocols/websocket) +- [Http](/sdk/js/6/protocols/http) +- [SocketIO](/sdk/js/6/protocols/socketio) + +## Volatile data + +You can tell the Kuzzle SDK to attach a set of "volatile" data to each request. You can set it as an object contained in the `volatile` field of the Kuzzle constructor. The response to a request containing volatile data will contain the same data in its `volatile` field. This can be useful, for example, in real-time notifications for [user join/leave notifications](/core/1/api/essentials/volatile-data/) to provide additional informations about the client who sent the request. + +Note that you can also set volatile data on a per-request basis (on requests that accept a `volatile` field in their `options` argument). In this case, per-request volatile data will be merged with the global `volatile` object set in the constructor. Per-request fields will override global ones. \ No newline at end of file diff --git a/doc/6/core-classes/kuzzle/play-queue/index.md b/doc/6/core-classes/kuzzle/play-queue/index.md new file mode 100644 index 000000000..f614b16ca --- /dev/null +++ b/doc/6/core-classes/kuzzle/play-queue/index.md @@ -0,0 +1,25 @@ +--- +code: true +type: page +title: playQueue +description: Play the offline request queue +--- + +# playQueue + +Plays the requests queued during `offline` state. +Works only if the SDK is not in a `offline` state, and if the `autoReplay` option is set to `false`. + +## Arguments + +```js +playQueue(); +``` + +## Return + +The `Kuzzle` instance. + +## Usage + +<<< ./snippets/play-queue.js diff --git a/doc/6/core-classes/kuzzle/play-queue/snippets/play-queue.js b/doc/6/core-classes/kuzzle/play-queue/snippets/play-queue.js new file mode 100644 index 000000000..463d99a18 --- /dev/null +++ b/doc/6/core-classes/kuzzle/play-queue/snippets/play-queue.js @@ -0,0 +1,7 @@ +try { + kuzzle.playQueue(); + + console.log('Start playing offline queue'); +} catch (error) { + console.error(error); +} diff --git a/doc/6/core-classes/kuzzle/play-queue/snippets/play-queue.test.yml b/doc/6/core-classes/kuzzle/play-queue/snippets/play-queue.test.yml new file mode 100644 index 000000000..a3507d292 --- /dev/null +++ b/doc/6/core-classes/kuzzle/play-queue/snippets/play-queue.test.yml @@ -0,0 +1,11 @@ +--- +name: kuzzle#playQueue +description: Play the requests queued +hooks: + before: + after: +template: without-connect +expected: Start playing offline queue + +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle/properties/index.md b/doc/6/core-classes/kuzzle/properties/index.md new file mode 100644 index 000000000..81006cdec --- /dev/null +++ b/doc/6/core-classes/kuzzle/properties/index.md @@ -0,0 +1,86 @@ +--- +code: false +type: page +title: Properties +description: Kuzzle class properties +order: 10 +--- + +# Read-only properties + +| Property name | Type | Description | +| -------------------- | -------- | ---------------------| +| `authenticated` | 
boolean
| Returns `true` if the SDK holds a valid token | +| `connected` | 
boolean
| Returns `true` if the SDK is currently connected to a Kuzzle server. | +| `offlineQueue` | 
object[]
| Contains the queued requests during offline mode | +| `protocol` | 
Protocol
| Protocol used by the SDK | + +### connected + +The `connected` property wraps the underlying protocol `connected` property. +See the associated documentation: + - [Http.connected](/sdk/js/6/protocols/http/properties) + - [WebSocket.connected](/sdk/js/6/protocols/websocket/properties) + - [SocketIO.connected](/sdk/js/6/protocols/socketio/properties) + +# Writable properties + +| Property name | Type | Description | +| -------------------- | -------- | ---------------------| +| `autoQueue` | 
boolean
| If `true`, automatically queues all requests during offline mode | +| `autoReplay` | 
boolean
| If `true`, automatically replays queued requests on a `reconnected` event | +| `autoResubscribe` | 
boolean
| If `true`, automatically renews all subscriptions on a `reconnected` event | +| `jwt` | 
string
| Authentication token | +| `offlineQueueLoader` | 
function
| Called before dequeuing requests after exiting offline mode, to add items at the beginning of the offline queue | +| `queueFilter` | 
function
| Custom function called during offline mode to filter queued requests on-the-fly | +| `queueMaxSize` | 
number
| Number of maximum requests kept during offline mode| +| `queueTTL` | 
number
| Time a queued request is kept during offline mode, in milliseconds | +| `replayInterval` | 
number
| Delay between each replayed requests | +| `volatile` | 
object
| Common volatile data, will be sent to all future requests | + +### offlineQueueLoader + +The `offlineQueueLoader` property must be set with a function of one of the following formats: + +```js +Object[] offlineQueueLoader() + +Promise offlineQueueLoader() +``` + +The returned (or resolved) array must contain objects, each with the following properties: + +| Property | Type | Description | +|---|---|---| +| `query` | 
object
| Object representing the request that is about to be sent to Kuzzle, following the [Kuzzle API](/core/1/api/essentials/query-syntax) format | +| `reject` | 
function
| A [Promise.reject](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject) function | +| `resolve` | 
function
| A [Promise.resolve](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve) function | + +### queueFilter + +The `queueFilter` property must be set with a function of the following form: + +```js +boolean queueFilter(request) +``` + +The `request` argument is an object representing the request that is about to be sent to Kuzzle, following the [Kuzzle API](/core/1/api/essentials/query-syntax) format. + +### queueMaxSize + +This property defines the size of the offline buffer, which is a first-in first-out (FIFO) queue. + +This means that if the `queueMaxSize` limit is reached, older requests are discarded to make room for newer requests. + +If `queueMaxSize` is set to a number lower than, or equal to `0`, then an unlimited number of requests is kept in the offline buffer. +Note that doing so may lead to a crash due to memory saturation, if there are too many requests held in memory. + +### queueTTL + +If the `queueTTL` property is set to a number lower than, or equal to `0`, then requests never expire and are kept indefinitely. + +### volatile + +Multiple methods allow passing specific `volatile` data. + +These `volatile` data will be merged with the global Kuzzle `volatile` object when sending the request, with the request specific `volatile` taking priority over the global ones. diff --git a/doc/6/core-classes/kuzzle/query/index.md b/doc/6/core-classes/kuzzle/query/index.md new file mode 100644 index 000000000..be63f82a0 --- /dev/null +++ b/doc/6/core-classes/kuzzle/query/index.md @@ -0,0 +1,58 @@ +--- +code: true +type: page +title: query +description: Base method to send API query to Kuzzle +--- + +# query + +Base method used to send queries to Kuzzle, following the [API Documentation](/core/1/api). + +:::warning +This is a low-level method, exposed to allow advanced SDK users to bypass high-level methods. +::: + +## Arguments + +```js +query(request, [options]); +``` + +
+ +| Argument | Type | Description | +| --------- | ----------------- | ---------------------- | +| `request` | 
object
| API request | +| `options` | 
object
| Optional query options | + +### request + +All properties necessary for the Kuzzle API can be added in the request object. +The following properties are the most common. + +| Property | Type | Description | +| ------------ | ----------------- | ---------------------------------------- | +| `controller` | 
string
| Controller name (mandatory) | +| `action` | 
string
| Action name (mandatory) | +| `body` | 
object
| Query body for this action | +| `index` | 
string
| Index name for this action | +| `collection` | 
string
| Collection name for this action | +| `_id` | 
string
| id for this action | +| `volatile` | 
object
| Additional information to send to Kuzzle | + +### options + +Additional query options + +| Property | Type
(default) | Description | +| ---------- | ------------------------------- | --------------------------------- | +| `queuable` | 
boolean

(`true`) | Make this request queuable or not | + +## Resolves + +Resolve to the raw Kuzzle API response. See the [API Documentation](/core/1/api). + +## Usage + +<<< ./snippets/query.js diff --git a/doc/6/core-classes/kuzzle/query/snippets/query.js b/doc/6/core-classes/kuzzle/query/snippets/query.js new file mode 100644 index 000000000..e06d967f5 --- /dev/null +++ b/doc/6/core-classes/kuzzle/query/snippets/query.js @@ -0,0 +1,50 @@ +const request = { + controller: 'document', + action: 'create', + index: 'nyc-open-data', + collection: 'yellow-taxi', + _id: 'my-custom-document-id', + refresh: 'wait_for', // Additional property allowed for this API action + body: { + trip_distance: 4.23, + passenger_count: 2 + } +}; + +try { + const response = await kuzzle.query(request); + console.log(response); + /* + { requestId: '49ffb6db-bdff-45b9-b3f6-00442f472393', + status: 200, + error: null, + controller: 'document', + action: 'create', + collection: 'yellow-taxi', + index: 'nyc-open-data', + volatile: { sdkVersion: '6.0.0-beta-2' }, + room: '49ffb6db-bdff-45b9-b3f6-00442f472393', + result: + { _index: 'nyc-open-data', + _type: 'yellow-taxi', + _id: 'my-custom-document-id', + _version: 1, + result: 'created', + _shards: { total: 2, successful: 1, failed: 0 }, + created: true, + _source: + { trip_distance: 4.23, + passenger_count: 2, + _kuzzle_info: + { author: '-1', + createdAt: 1532529302225, + updatedAt: null, + updater: null, + active: true, + deletedAt: null } } } } + */ + + console.log('Document created'); +} catch (error) { + console.error(error); +} diff --git a/doc/6/core-classes/kuzzle/query/snippets/query.test.yml b/doc/6/core-classes/kuzzle/query/snippets/query.test.yml new file mode 100644 index 000000000..0b5358454 --- /dev/null +++ b/doc/6/core-classes/kuzzle/query/snippets/query.test.yml @@ -0,0 +1,14 @@ +--- +name: kuzzle#query +description: Sends a request to Kuzzle API +hooks: + before: | + curl -X POST kuzzle:7512/nyc-open-data/_create + curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi + curl -X DELETE kuzzle:7512/nyc-open-data/yellow-taxi/my-custom-document-id + after: +template: default +expected: Document created + +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle/start-queuing/index.md b/doc/6/core-classes/kuzzle/start-queuing/index.md new file mode 100644 index 000000000..bc6899895 --- /dev/null +++ b/doc/6/core-classes/kuzzle/start-queuing/index.md @@ -0,0 +1,25 @@ +--- +code: true +type: page +title: startQueuing +description: Starts the requests queuing +--- + +# startQueuing + +Starts the requests queuing. +Works only in `offline` state, and if the `autoQueue` option is set to false. + +## Arguments + +```js +startQueuing(); +``` + +## Return + +The `Kuzzle` instance. + +## Usage + +<<< ./snippets/start-queuing.js diff --git a/doc/6/core-classes/kuzzle/start-queuing/snippets/start-queuing.js b/doc/6/core-classes/kuzzle/start-queuing/snippets/start-queuing.js new file mode 100644 index 000000000..787e2518b --- /dev/null +++ b/doc/6/core-classes/kuzzle/start-queuing/snippets/start-queuing.js @@ -0,0 +1,7 @@ +try { + kuzzle.startQueuing(); + + console.log('Start queuing requests'); +} catch (error) { + console.error(error); +} diff --git a/doc/6/core-classes/kuzzle/start-queuing/snippets/start-queuing.test.yml b/doc/6/core-classes/kuzzle/start-queuing/snippets/start-queuing.test.yml new file mode 100644 index 000000000..914f4ac01 --- /dev/null +++ b/doc/6/core-classes/kuzzle/start-queuing/snippets/start-queuing.test.yml @@ -0,0 +1,11 @@ +--- +name: kuzzle#startQueuing +description: Starts the requests queuing +hooks: + before: + after: +template: without-connect +expected: Start queuing requests + +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle/stop-queuing/index.md b/doc/6/core-classes/kuzzle/stop-queuing/index.md new file mode 100644 index 000000000..1cdb49faf --- /dev/null +++ b/doc/6/core-classes/kuzzle/stop-queuing/index.md @@ -0,0 +1,25 @@ +--- +code: true +type: page +title: stopQueuing +description: Stops the requests queuing +--- + +# stopQueuing + +Stops the requests queuing. +Works only in `offline` state, and if the `autoQueue` option is set to false. + +## Arguments + +```js +stopQueuing(); +``` + +## Return + +The `Kuzzle` instance. + +## Usage + +<<< ./snippets/stop-queuing.js diff --git a/doc/6/core-classes/kuzzle/stop-queuing/snippets/stop-queuing.js b/doc/6/core-classes/kuzzle/stop-queuing/snippets/stop-queuing.js new file mode 100644 index 000000000..782278ef6 --- /dev/null +++ b/doc/6/core-classes/kuzzle/stop-queuing/snippets/stop-queuing.js @@ -0,0 +1,7 @@ +try { + kuzzle.stopQueuing(); + + console.log('Stop queuing requests'); +} catch (error) { + console.error(error); +} diff --git a/doc/6/core-classes/kuzzle/stop-queuing/snippets/stop-queuing.test.yml b/doc/6/core-classes/kuzzle/stop-queuing/snippets/stop-queuing.test.yml new file mode 100644 index 000000000..d0709b139 --- /dev/null +++ b/doc/6/core-classes/kuzzle/stop-queuing/snippets/stop-queuing.test.yml @@ -0,0 +1,11 @@ +--- +name: kuzzle#stopQueuing +description: Stops the requests queuing +hooks: + before: + after: +template: without-connect +expected: Stop queuing requests + +sdk: js +version: 6 diff --git a/doc/6/core-classes/kuzzle/use-controller/index.md b/doc/6/core-classes/kuzzle/use-controller/index.md new file mode 100644 index 000000000..e5fcbd2a0 --- /dev/null +++ b/doc/6/core-classes/kuzzle/use-controller/index.md @@ -0,0 +1,34 @@ +--- +code: true +type: page +title: useController +description: Adds a new controller to the SDK +--- + +# useController + +Adds a new controller to the SDK. + +*See also:* + - *[Extend the SDK](/sdk/js/6/essentials/extend-sdk)* + +## Arguments + +```js +useController (ControllerClass, accessor); +``` + +
+ +| Argument | Type | Description | +| -------------- | --------- | ------------- | +| `ControllerClass` | 
Class
| Controller class. Must inherit from [BaseController](/sdk/js/6/core-classes/base-controller) | +| `accessor` | 
string
| Accessor name for the controller in the Kuzzle object | + +## Returns + +Returns the Kuzzle object. + +## Usage + +<<< ./snippets/use-controller.js \ No newline at end of file diff --git a/doc/6/core-classes/kuzzle/use-controller/snippets/use-controller.js b/doc/6/core-classes/kuzzle/use-controller/snippets/use-controller.js new file mode 100644 index 000000000..c63c4f286 --- /dev/null +++ b/doc/6/core-classes/kuzzle/use-controller/snippets/use-controller.js @@ -0,0 +1,35 @@ +class TaxiController extends BaseController { + constructor (kuzzle) { + super(kuzzle, 'my-plugin/taxi'); + } + + enroll () { + return this.query({ + action: 'enroll' + }); + } +} + +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); + +// Add the custom SDK controller +kuzzle.useController(TaxiController, 'taxi'); + +const run = async () => { + try { + await kuzzle.connect(); + + // Call the custom SDK controller action + console.log(await kuzzle.taxi.enroll()); + + console.log('Success'); + } catch (error) { + console.error(error); + } finally { + kuzzle.disconnect(); + } +}; + +run(); diff --git a/doc/6/core-classes/kuzzle/use-controller/snippets/use-controller.test.yml b/doc/6/core-classes/kuzzle/use-controller/snippets/use-controller.test.yml new file mode 100644 index 000000000..f16fbf941 --- /dev/null +++ b/doc/6/core-classes/kuzzle/use-controller/snippets/use-controller.test.yml @@ -0,0 +1,11 @@ +--- +name: kuzzle#useController +description: Adds a new controller to the SDK +hooks: + before: + after: +template: controller +expected: Success + +sdk: js +version: 6 \ No newline at end of file diff --git a/doc/6/core-classes/profile/getRoles/index.md b/doc/6/core-classes/profile/getRoles/index.md new file mode 100644 index 000000000..b0457e1ba --- /dev/null +++ b/doc/6/core-classes/profile/getRoles/index.md @@ -0,0 +1,24 @@ +--- +code: true +type: page +title: getRoles +description: Profile getRoles method +--- + +# getRoles + +Loads information about the profile roles. + +## Arguments + +```js +getRoles(); +``` + +## Resolve + +Resolves to an array of [Role](/sdk/js/6/core-classes/role/). + +## Usage + +<<< ./snippets/getRoles.js diff --git a/doc/6/core-classes/profile/getRoles/snippets/getRoles.js b/doc/6/core-classes/profile/getRoles/snippets/getRoles.js new file mode 100644 index 000000000..5ded07431 --- /dev/null +++ b/doc/6/core-classes/profile/getRoles/snippets/getRoles.js @@ -0,0 +1,28 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const user = await kuzzle.auth.getCurrentUser(); + + const profiles = await user.getProfiles(); + + const roles = await profiles[0].getRoles(); + console.log(roles); + /* + [ + Role { + _id: 'default', + controllers: { + '*': { + actions: { + '*': true + } + } + } + } + ] + */ +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/core-classes/profile/getRoles/snippets/getRoles.test.yml b/doc/6/core-classes/profile/getRoles/snippets/getRoles.test.yml new file mode 100644 index 000000000..0ddd2c4b4 --- /dev/null +++ b/doc/6/core-classes/profile/getRoles/snippets/getRoles.test.yml @@ -0,0 +1,12 @@ +name: user#getRoles +description: Loads informations about user roles +hooks: + before: | + curl -X DELETE kuzzle:7512/users/foo + curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: +template: default +expected: + - Profile { _id: \'default\' +sdk: js +version: 6 diff --git a/doc/6/core-classes/profile/index.md b/doc/6/core-classes/profile/index.md new file mode 100644 index 000000000..ba2bda51a --- /dev/null +++ b/doc/6/core-classes/profile/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: Profile +description: Profile class documentation +order: 510 +--- diff --git a/doc/6/core-classes/profile/introduction/index.md b/doc/6/core-classes/profile/introduction/index.md new file mode 100644 index 000000000..783f3a717 --- /dev/null +++ b/doc/6/core-classes/profile/introduction/index.md @@ -0,0 +1,13 @@ +--- +code: false +type: page +title: Introduction +description: Profile class +order: 0 +--- + +# Profile + +This class represents a Kuzzle Profile. + +Refer to the [Security guide](/core/1/guides/essentials/security/#defining-profiles) for more information about profiles. diff --git a/doc/6/core-classes/profile/properties/index.md b/doc/6/core-classes/profile/properties/index.md new file mode 100644 index 000000000..c6dddc9eb --- /dev/null +++ b/doc/6/core-classes/profile/properties/index.md @@ -0,0 +1,23 @@ +--- +code: false +type: page +title: Properties +description: Profile Properties +order: 10 +--- + +# Properties + +| Property | Type | Description | +|--- |--- |--- | +| `_id` | 
string
| Profile ID | +| `policies` | 
object[]
| Array of policies for this profile | + +### policies + +Each policy object can contain the following properties: + +| Property | Type | Description | +|--- |--- |--- | +| `roleId` | 
string
| Roles IDs for this user | +| `restrictedTo` | 
object[]
| Array of object containing indexes and collections which the profile is restricted to | diff --git a/doc/6/core-classes/role/index.md b/doc/6/core-classes/role/index.md new file mode 100644 index 000000000..25fb73bea --- /dev/null +++ b/doc/6/core-classes/role/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: Role +description: Role class documentation +order: 510 +--- diff --git a/doc/6/core-classes/role/introduction/index.md b/doc/6/core-classes/role/introduction/index.md new file mode 100644 index 000000000..f1748eade --- /dev/null +++ b/doc/6/core-classes/role/introduction/index.md @@ -0,0 +1,13 @@ +--- +code: false +type: page +title: Introduction +description: Role class +order: 0 +--- + +# Role + +This class represents a Kuzzle Role. + +Refer to the [Security guide](/core/1/guides/essentials/security/#defining-roles) for more information about roles. \ No newline at end of file diff --git a/doc/6/core-classes/role/properties/index.md b/doc/6/core-classes/role/properties/index.md new file mode 100644 index 000000000..c3fe42c7c --- /dev/null +++ b/doc/6/core-classes/role/properties/index.md @@ -0,0 +1,16 @@ +--- +code: false +type: page +title: Properties +description: Role class properties +order: 10 +--- + +# Properties + +Available properties: + +| Property | Type | Description | +|--- |--- |--- | +| `_id` | 
string
| Role unique identifier | +| `controllers` | 
object
| Object defining controller actions allowed by this role | diff --git a/doc/6/core-classes/search-result/index.md b/doc/6/core-classes/search-result/index.md new file mode 100644 index 000000000..5e822dcbe --- /dev/null +++ b/doc/6/core-classes/search-result/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: SearchResult +description: SearchResult class documentation +order: 510 +--- diff --git a/doc/6/core-classes/search-result/introduction/index.md b/doc/6/core-classes/search-result/introduction/index.md new file mode 100644 index 000000000..5690ee10d --- /dev/null +++ b/doc/6/core-classes/search-result/introduction/index.md @@ -0,0 +1,15 @@ +--- +code: false +type: page +title: Introduction +description: SearchResult class +order: 0 +--- + +# SearchResult + +The class is used to retrieve the subsequent paginated results of a search query. +The following methods returns a `SearchResult`: + +- [document:search](/sdk/js/6/controllers/document/search) +- [collection:searchSpecifications](/sdk/js/6/controllers/collection/search-specifications) diff --git a/doc/6/core-classes/search-result/next/index.md b/doc/6/core-classes/search-result/next/index.md new file mode 100644 index 000000000..ace94e5da --- /dev/null +++ b/doc/6/core-classes/search-result/next/index.md @@ -0,0 +1,63 @@ +--- +code: true +type: page +title: next +description: SearchResult next method +order: 200 +--- + +# SearchResult + +Returns a new `SearchResult` object which contain the subsequent results of the search. + +## Arguments + +```js +next(); +``` + +## Behaviour of the next method + +In order to be able to compute the next search page, some initial conditions must be met. + +Depending on the arguments given to the initial search, thhe `next` method will pick one of the following policies, by decreasing order of priority (i.e. a search including a `scroll`, `sort` and `size` will use the `scroll` policy). + +If no policy is applicable, the `next` method will throw an exception. + +:::info +When processing a large number of documents (i.e. more than 1000), it is advised to use a scroll cursor. + +It is also the only method guaranteeing that all matching documents will be retrieved and no duplicates will be included. +::: + +## Usage with scroll + +**This is the preferred way to get some paginated results**. + +If the original search is given a `scroll` parameter, the `next` method will use a cursor to paginate results. + +The results that are returned from a scroll request reflect the state of the index at the time the initial `search` request was performed, like a snapshot in time. + +As such, even if some documents are added or deleted from the database between two calls to `next`, the result is garanteed to include all items matching the query at the time the initial `search` was sent and to not get any duplicate between two search pages. + +<<< ./snippets/scroll.js + +## Usage with sort / size + +If the initial search is given some `sort` and `size` parameters, the `next` method will retrieve the next items matching the sort. + +To avoid too many duplicates, it is advised to provide a sort combination that will always identify one item only. The recommended way is to use the field `_uid` which is certain to contain one unique value for each document. + +Because this method does not freeze the research between two calls, if some updates are applied to the database between two calls, it is still possible to miss some documents and/or to get some duplicates between search pages. + +## Usage with from / size + +If the initial search is given some `from` and `size` parameters, the `next` method will increment the `from` parameter to retrieved the next results. + +Because this method does not freeze the research between two calls, if some updates are applied to the database between two calls, it is possible to miss some documents and/or to get some duplicates between search pages. + +:::info +It is not possible to retrieve more than 10000 items using this method. Above that limit, any call to `next` will throw an Exception. +::: + +<<< ./snippets/fromsize.js diff --git a/doc/6/core-classes/search-result/next/snippets/fromsize.js b/doc/6/core-classes/search-result/next/snippets/fromsize.js new file mode 100644 index 000000000..74fb61abe --- /dev/null +++ b/doc/6/core-classes/search-result/next/snippets/fromsize.js @@ -0,0 +1,69 @@ +const suv = { category: 'suv' }; + +try { + const requests = []; + + for (let i = 0; i < 10; i++) { + requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', suv)); + } + + await Promise.all(requests); + + // Waits documents to be indexed + await kuzzle.index.refresh('nyc-open-data'); + + const searchOptions = { + from: 1, + size: 5 + }; + + const results = await kuzzle.document.search( + 'nyc-open-data', + 'yellow-taxi', + { + query: { + match: { + category: 'suv' + } + } + }, + searchOptions + ); + + const nextResults = await results.next(); + + console.log(`Successfully retrieved ${nextResults.fetched} documents`); + console.log(nextResults); + /* + { + "aggregations": undefined, + "hits": [ + { + "_index": "nyc-open-data", + "_type": "yellow-taxi", + "_id": "AWgi6A1POQUM6ucJ3q06", + "_score": 0.046520017, + "_source": { + "category": "suv", + "_kuzzle_info": { + "author": "-1", + "createdAt": 1546773859655, + "updatedAt": null, + "updater": null, + "active": true, + "deletedAt": null + } + } + }, + ... + ] + }, + "total": 10, + "fetched": 10, + "scroll_id": undefined, + "from": 1, + "size": 5 + */ +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/core-classes/search-result/next/snippets/fromsize.test.yml b/doc/6/core-classes/search-result/next/snippets/fromsize.test.yml new file mode 100644 index 000000000..b23305a90 --- /dev/null +++ b/doc/6/core-classes/search-result/next/snippets/fromsize.test.yml @@ -0,0 +1,13 @@ +name: searchresult#fromsize +description: Next method with from/size +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Successfully retrieved 10 documents +sdk: js +version: 6 diff --git a/doc/6/core-classes/search-result/next/snippets/scroll.js b/doc/6/core-classes/search-result/next/snippets/scroll.js new file mode 100644 index 000000000..c2e4f83ac --- /dev/null +++ b/doc/6/core-classes/search-result/next/snippets/scroll.js @@ -0,0 +1,74 @@ +const suv = { category: 'suv' }; + +try { + const requests = []; + + for (let i = 0; i < 10; i++) { + requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', suv)); + } + + await Promise.all(requests); + + // Waits documents to be indexed + await kuzzle.index.refresh('nyc-open-data'); + + const searchOptions = { + scroll: '1m', + size: 5 + }; + + let results = await kuzzle.document.search( + 'nyc-open-data', + 'yellow-taxi', + { + query: { + match: { + category: 'suv' + } + } + }, + searchOptions + ); + + // Fetch the next fetch results and push them into the 'documents' array + const documents = []; + + while (results) { + results.hits.forEach(hit => documents.push(hit._source)); + results = await results.next(); + } + + console.log(results); + /* + { + "aggregations": undefined, + "hits": [ + { + "_index": "nyc-open-data", + "_type": "yellow-taxi", + "_id": "AWgi6A1POQUM6ucJ3q06", + "_score": 0.046520017, + "_source": { + "category": "suv", + "_kuzzle_info": { + "author": "-1", + "createdAt": 1546773859655, + "updatedAt": null, + "updater": null, + "active": true, + "deletedAt": null + } + } + }, + ... + ] + }, + "total": 10, + "fetched": 10, + "scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAAAqFnQ5NU9sZWFaUTRhd2VHNU5KZzVEQ" + */ + + console.log(`Successfully retrieved ${documents.length} documents`); +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/core-classes/search-result/next/snippets/scroll.test.yml b/doc/6/core-classes/search-result/next/snippets/scroll.test.yml new file mode 100644 index 000000000..6daa0f360 --- /dev/null +++ b/doc/6/core-classes/search-result/next/snippets/scroll.test.yml @@ -0,0 +1,13 @@ +name: searchresult#scroll +description: Next method with scroll +hooks: + before: | + curl -XDELETE kuzzle:7512/nyc-open-data + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: | + curl -XDELETE kuzzle:7512/nyc-open-data +template: default +expected: Successfully retrieved 10 documents +sdk: js +version: 6 diff --git a/doc/6/core-classes/search-result/properties/index.md b/doc/6/core-classes/search-result/properties/index.md new file mode 100644 index 000000000..d2cddde51 --- /dev/null +++ b/doc/6/core-classes/search-result/properties/index.md @@ -0,0 +1,27 @@ +--- +code: false +type: page +title: Properties +description: SearchResult class properties +order: 100 +--- + +# Properties + +| Property | Type | Description | +|--- |--- |--- | +| `aggregations` | 
object
| Search aggregations if any | +| `hits` | 
object[]
| Array containing the retrieved items for the current page | +| `total` | 
number
| Total number of items matching the given query in Kuzzle database | +| `fetched` | 
number
| Number of retrieved items so far | +| `scroll_id` | 
string
| Scroll identifier if the search was given a `scroll` parameter | + +### hits + +Each object of the `hits` array contain the following properties: + +| Property | Type | Description | +|--- |--- |--- | +| `_id` | 
string
| Document ID | +| `_score` | 
number
| [Relevance score](https://www.elastic.co/guide/en/elasticsearch/guide/current/relevance-intro.html) | +| `_source` | 
object
| Document content | diff --git a/doc/6/core-classes/user/getProfiles/index.md b/doc/6/core-classes/user/getProfiles/index.md new file mode 100644 index 000000000..87a9895ee --- /dev/null +++ b/doc/6/core-classes/user/getProfiles/index.md @@ -0,0 +1,24 @@ +--- +code: true +type: page +title: getProfiles +description: User getProfiles method +--- + +# getProfiles + +Loads information about the user profiles. + +## Arguments + +```js +getProfiles(); +``` + +## Resolve + +Resolves to an array of [Profile](/sdk/js/6/core-classes/profile). + +## Usage + +<<< ./snippets/getProfiles.js diff --git a/doc/6/core-classes/user/getProfiles/snippets/getProfiles.js b/doc/6/core-classes/user/getProfiles/snippets/getProfiles.js new file mode 100644 index 000000000..e21000022 --- /dev/null +++ b/doc/6/core-classes/user/getProfiles/snippets/getProfiles.js @@ -0,0 +1,24 @@ +const credentials = { username: 'foo', password: 'bar' }; + +try { + await kuzzle.auth.login('local', credentials); + + const user = await kuzzle.auth.getCurrentUser(); + + const profiles = await user.getProfiles(); + console.log(profiles); + /* + [ + Profile { + _id: 'default', + policies: [ + { + roleId: 'default' + } + ] + } + ] + */ +} catch (error) { + console.error(error.message); +} diff --git a/doc/6/core-classes/user/getProfiles/snippets/getProfiles.test.yml b/doc/6/core-classes/user/getProfiles/snippets/getProfiles.test.yml new file mode 100644 index 000000000..f23afa975 --- /dev/null +++ b/doc/6/core-classes/user/getProfiles/snippets/getProfiles.test.yml @@ -0,0 +1,12 @@ +name: user#getProfiles +description: Loads informations about user profiles +hooks: + before: | + curl -X DELETE kuzzle:7512/users/foo + curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}' + after: +template: default +expected: + - Role { _id: \'default\' +sdk: js +version: 6 diff --git a/doc/6/core-classes/user/index.md b/doc/6/core-classes/user/index.md new file mode 100644 index 000000000..f5b765f27 --- /dev/null +++ b/doc/6/core-classes/user/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: User +description: User class documentation +order: 510 +--- diff --git a/doc/6/core-classes/user/introduction/index.md b/doc/6/core-classes/user/introduction/index.md new file mode 100644 index 000000000..5bc9f6142 --- /dev/null +++ b/doc/6/core-classes/user/introduction/index.md @@ -0,0 +1,18 @@ +--- +code: false +type: page +title: Introduction +description: User class +order: 0 +--- + +# User + +This class represents a Kuzzle User. + +Refer to the [Security guide](/core/1/guides/essentials/security/) for more information about users. + +The following methods return a `User` object: + +- [auth:getCurrentUser](/sdk/js/6/controllers/auth/get-current-user) +- [auth:updateSelf](/sdk/js/6/controllers/auth/update-self) diff --git a/doc/6/core-classes/user/properties/index.md b/doc/6/core-classes/user/properties/index.md new file mode 100644 index 000000000..f1995aa86 --- /dev/null +++ b/doc/6/core-classes/user/properties/index.md @@ -0,0 +1,24 @@ +--- +code: false +type: page +title: Properties +description: User class properties +order: 10 +--- + +# Properties + + +| Property | Type | Description | +|--- |--- |--- | +| `_id` | 
string
| User ID (kuid) | +| `content` | 
object
| User internal content | + +### content + +The `content` property is an object containing, alongside custom defined values, the following generic properties: + +| Property | Type | Description | +|--- |--- |--- | +| `profileIds` | 
string[]
| Profiles IDs for this user | +| `_kuzzle_info` | 
object
| [Kuzzle metadata](/core/1/guides/essentials/document-metadata/) | diff --git a/doc/6/essentials/error-handling/index.md b/doc/6/essentials/error-handling/index.md new file mode 100644 index 000000000..31249dc23 --- /dev/null +++ b/doc/6/essentials/error-handling/index.md @@ -0,0 +1,28 @@ +--- +code: false +type: page +title: Error Handling +description: How to handle errors with the SDK +order: 100 +--- + +# Error Handling + +All SDK methods return a promise, that can be rejected with a `KuzzleError` value in case of failure. + +[KuzzleError](/sdk/js/6/core-classes/kuzzle-error/introduction/) objects inherit the standard `Error` object, and add the following properties to it: + +| Property | Type | Description | +| -------- | ----------------- | ------------------------------------------------------------------------------------------ | +| `status` | 
number
| Status following [HTTP Standards](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) | +| `stack` | 
string
| Error stacktrace (Only in development mode) | + +You can find a detailed list of possible errors messages and statuses in the [documentation API](/core/1/api/essentials/errors). + +#### Example with a promise chain + +<<< ./snippets/error-handling.js + +#### Example with async/await + +<<< ./snippets/error-handling-async.js diff --git a/doc/6/essentials/error-handling/snippets/error-handling-async.js b/doc/6/essentials/error-handling/snippets/error-handling-async.js new file mode 100644 index 000000000..7ad0589e0 --- /dev/null +++ b/doc/6/essentials/error-handling/snippets/error-handling-async.js @@ -0,0 +1,8 @@ +try { + await kuzzle.index.create('nyc-open-data'); +} catch (error) { + if (error.status === 400) { + console.log(error.message); + console.log('Try with another name!'); + } +} diff --git a/doc/6/essentials/error-handling/snippets/error-handling-async.test.yml b/doc/6/essentials/error-handling/snippets/error-handling-async.test.yml new file mode 100644 index 000000000..8473fa704 --- /dev/null +++ b/doc/6/essentials/error-handling/snippets/error-handling-async.test.yml @@ -0,0 +1,10 @@ +name: essentials#errorHandlingAsync +description: How to handle errors with the SDK +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create + after: +template: default +expected: Try with another name! + +sdk: js +version: 6 diff --git a/doc/6/essentials/error-handling/snippets/error-handling.js b/doc/6/essentials/error-handling/snippets/error-handling.js new file mode 100644 index 000000000..3cde31af5 --- /dev/null +++ b/doc/6/essentials/error-handling/snippets/error-handling.js @@ -0,0 +1,8 @@ +kuzzle.index.create('nyc-open-data') + .then(() => 'do something') + .catch(error => { + if (error.status === 400) { + console.log(error.message); + console.log('Try with another name!'); + } + }); diff --git a/doc/6/essentials/error-handling/snippets/error-handling.test.yml b/doc/6/essentials/error-handling/snippets/error-handling.test.yml new file mode 100644 index 000000000..948f43353 --- /dev/null +++ b/doc/6/essentials/error-handling/snippets/error-handling.test.yml @@ -0,0 +1,10 @@ +name: essentials#errorHandling +description: How to handle errors with the SDK +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create + after: +template: thencatch +expected: Try with another name! + +sdk: js +version: 6 diff --git a/doc/6/essentials/events/index.md b/doc/6/essentials/events/index.md new file mode 100644 index 000000000..de31b9dda --- /dev/null +++ b/doc/6/essentials/events/index.md @@ -0,0 +1,101 @@ +--- +code: false +type: page +title: Events +description: SDK events system +order: 200 +--- + +# Events + +An event system allows to be notified when the SDK status changes. These events are issued by the [Kuzzle](/sdk/js/6/core-classes/kuzzle) SDK object. + +The API for interacting with events is described by our [KuzzleEventEmitter](/sdk/js/6/core-classes/kuzzle-event-emitter) class documentation. + +**Note:** listeners are called in the order of their insertion. + +# Emitted Events + +## connected + +Triggered when the SDK has successfully connected to Kuzzle. + +## discarded + +Triggered when Kuzzle discards a request, typically if no connection is established and the request is not queuable, either because the offline mode is not set or if set explicitely. + +**Callback arguments:** + +`@param {object} request`: the discarded [request](/core/1/api/essentials/query-syntax/) + +## disconnected + +Triggered when the current session has been unexpectedly disconnected. + +## loginAttempt + +Triggered when a login attempt completes, either with a success or a failure result. + +**Callback arguments:** + +`@param {object} data` + +| Property | Type | Description | +| --------- | ------------------ | --------------------------------- | +| `success` | 
boolean
| Indicate if login attempt succeed | +| `error` | 
string
| Error message when login fail | + +## networkError + +Triggered when the SDK has failed to connect to Kuzzle. + +**Callback arguments:** + +`@param {Error} error` + +| Property | Type | Description | +| --------- | ----------------- | ---------------------------------- | +| `message` | 
string
| Error description | +| `status` | 
number
| Error code | +| `stack` | 
string
| Stacktrace (development mode only) | + +## offlineQueuePop + +Triggered whenever a request is removed from the offline queue. + +**Callback arguments:** + +`@param {object} request`: the [request](/core/1/api/essentials/query-syntax/) removed from the queue + +## offlineQueuePush + +Triggered whenever a request is added to the offline queue. + +**Callback arguments:** + +`@param {object} data` + +| Property | Type | Description | +| --------- | ----------------- | ------------------------------------------------------------------ | +| `request` | 
object
| [Request](/core/1/api/essentials/query-syntax/) added to the queue | + +## queryError + +Triggered whenever Kuzzle responds with an error + +**Callback arguments:** + +`@param {object} data` + +| Property | Type | Description | +| --------- | ----------------- | ----------------------------- | +| `request` | 
object
| Request that causing an error | +| `error` | 
Error
| Error details | + +## reconnected + +Triggered when the current session has reconnected to Kuzzle after a disconnection, and only if `autoReconnect` is set to `true`. + +## tokenExpired + +Triggered when Kuzzle rejects a request because the authentication token has expired. diff --git a/doc/6/essentials/extend-sdk/index.md b/doc/6/essentials/extend-sdk/index.md new file mode 100644 index 000000000..df7387ec8 --- /dev/null +++ b/doc/6/essentials/extend-sdk/index.md @@ -0,0 +1,102 @@ +--- +code: false +type: page +title: Extends the SDK +description: Extend the SDK +order: 410 +--- + +# Extend the SDK with a custom SDK controller + + + +It is possible to extend the SDK's API by adding new controllers. + +These controllers correspond to [custom controllers created in a plugin](/core/1/plugins/guides/controllers). Thus, it is possible to use the actions of a core plugin in the SDK in the same way as the other actions of the Kuzzle API. + +## Define a custom SDK controller + +A custom SDK controller is a class inheriting from the [BaseController](/sdk/js/6/core-classes/base-controller) class and defining methods matching Kuzzle API actions. + +This base class is exposed alongside the other classes of the SDK module. + +After defining your new controller based on `BaseController`, you can add it to the SDK with the [Kuzzle.useController](/sdk/js/6/core-classes/kuzzle/use-controller) method. + +## Constructor + +The constructor of a custom SDK controller will be called by passing the SDK instance to it. It must call the parent constructor with this instance of the SDK and its name as defined in the API. + +For instance, if there is a plugin named `nyc-open-data-plugin`, extending Kuzzle's API with the following controller: + +```js +this.controllers = { + taxi: { + startDuty: request => this.startDuty(request) + } +} +``` + +Then the constructor of the custom SDK controller must specify its name as follows (see [how to query a custom API route](/core/1/plugins/guides/controllers/#querying-plugins-controllers) documentation): + +```js +const { BaseController } = require('kuzzle-sdk'); + +class TaxiController extends BaseController { + constructor (kuzzle) { + super(kuzzle, 'nyc-open-data-plugin/taxi'); + } +} +``` + +The controller name will then be injected into the requests sent with the [BaseController.query](/sdk/js/6/core-classes/base-controller/query) method. + +## Define custom SDK controller actions + +Each action of your custom SDK controller is a method of the class. + +These methods have to use the [BaseController.query](/sdk/js/6/core-classes/base-controller/query) method to invoke an API action. + +Extending the previous example, we now have: + +```js +const { BaseController } = require('kuzzle-sdk'); + +class TaxiController extends BaseController { + constructor (kuzzle) { + super(kuzzle, 'nyc-open-data-plugin/taxi'); + } + + startDuty (driver) { + const apiRequest = { + action: 'startDuty', + body: { + driver + } + }; + + return this.query(apiRequest) + .then(response => response.result); + } +} +``` + +## Add a custom SDK controller to the SDK + +Once you have defined your custom SDK controller, you can add it to the SDK with the [Kuzzle.useController](/sdk/js/6/core-classes/kuzzle/use-controller) method. + + +You can then use the actions of your plugins in the same way as the rest of the Kuzzle API by taking advantage of authentication, offline mode management, etc. + +```js +const + TaxiController = require('./taxiController'), + { Kuzzle, WebSocket } = require('kuzzle-sdk'); + +const kuzzle = new Kuzzle(new WebSocket('localhost')); + +kuzzle.useController(TaxiController, 'taxi'); + +await kuzzle.connect(); + +await kuzzle.taxi.startDuty('lia meh ry'); +``` diff --git a/doc/6/essentials/index.md b/doc/6/essentials/index.md new file mode 100644 index 000000000..41c639b95 --- /dev/null +++ b/doc/6/essentials/index.md @@ -0,0 +1,7 @@ +--- +code: false +type: branch +order: 100 +title: Essentials +description: Javascript SDK v6.x essential notions +--- diff --git a/doc/6/essentials/offline-tools/index.md b/doc/6/essentials/offline-tools/index.md new file mode 100644 index 000000000..a77c60213 --- /dev/null +++ b/doc/6/essentials/offline-tools/index.md @@ -0,0 +1,98 @@ +--- +code: false +type: page +title: Offline Tools +description: Tools to handle the loss of connection to the Kuzzle server +order: 400 +--- + +# Offline tools + +The Kuzzle SDK provides a set of properties that helps your application to be resilient to the loss of network connection +during its lifespan. + +## Contructor options and properties + +These properties can be set in the `options` object when [instantiating a new SDK](/sdk/js/6/core-classes/kuzzle/constructor/#arguments). + +Some of them are also [writable properties](/sdk/js/6/core-classes/kuzzle/properties) available after SDK instantiation. + +### autoQueue + +A writable `boolean` telling the SDK whether to automatically queue requests during the `offline` state or not. + +Default value: `false` + +### autoReconnect + +A writable `boolean` telling the SDK whether to automatically reconnect or not to Kuzzle after a connection loss. + +Default value: *Depends on the Protocol* + +### autoReplay + +A writable `boolean` telling the SDK whether to automatically send or not the requests in the `offlineQueue` on a +`reconnected` event. + +Default value: `false` + +### autoResubscribe + +A writable `boolean` telling the SDK whether to automatically renew or not all subscriptions on a reconnected event. + +Default value: `true` + +### offlineQueue + +A read-only `Array` containing the requests queued while the SDK is in the `offline` state (it behaves like a FIFO queue). + +### offlineQueueLoader + +A writable `Function` called by the SDK before playing the requests in the `offlineQueue`. This function takes no arguments +and returns an array of `Request` that are added on top of the `offlineQueue`. Use it to inject new requests to be played +before the queue. + +### queueFilter + +A writable `Function` called by the SDK each time a `Request` need to be queued. The `Request` is passed as the only argument +to the function and is queued only if the function returns `true`. Use it to define which requests are allowed to be queued. + +### queueMaxSize + +A writable `number` defining the maximun size of the `offlineQueue`. + +Default value: `500` + +### queueTTL + +A writable `number` defining the time in milliseconds a queued request is kept in the `offlineQueue`. + +Default value: `120000` + +### reconnectionDelay + +A read-only `number` specifying the time in milliseconds between different reconnection attempts. + +Default value: *Depends on the Protocol* + +## Methods + +### [flushQueue()](/sdk/js/6/core-classes/kuzzle/flush-queue) + +Empties the `offlineQueue` without sending the requests to Kuzzle. + +### [playQueue()](/sdk/js/6/core-classes/kuzzle/play-queue) + +Sends to Kuzzle all the requests in the `offlineQueue`. Works only if the SDK is not in a `offline` state, and if the +`autoReplay` option is set to false. + +### [startQueuing()](/sdk/js/6/core-classes/kuzzle/start-queuing/) + +Starts queuing requests when in `offline` state. Requests will be put in the `offlineQueue` array instead of being discarded, until `stopQueuing` is called. +Works only in `offline` state when the `autoQueue` option is set to `false`. Call `playQueue` to send to Kuzzle the +requests in the queue, once the SDK state passes to `online`. Call `flushQueue` to empty the queue without sending the requests. + +### [stopQueuing()](/sdk/js/6/core-classes/kuzzle/stop-queuing) + +Stop queuing the requests. Requests will no more be put in the `offlineQueue`, they will be discarded. +Works only in the `offline` state, and if the `autoQueue` option is set to `false`. diff --git a/doc/6/essentials/realtime-notifications/index.md b/doc/6/essentials/realtime-notifications/index.md new file mode 100644 index 000000000..a06b06aa0 --- /dev/null +++ b/doc/6/essentials/realtime-notifications/index.md @@ -0,0 +1,69 @@ +--- +code: false +type: page +title: Realtime notifications +description: List of realtime notifications sent by Kuzzle +order: 300 +--- + +# Notifications + +The [realtime.subscribe](/sdk/js/6/controllers/realtime/) method takes a callback argument, called with a notification object, whose properties depends on the type of notification received. + +## Document & messages + +These notifications represent [documents changes & messages](/core/1/api/essentials/notifications#documents-changes-messages). + +| Property | Type | Description | +| ------------ | ----------------- | ----------------------------------------------------------------------------------------------------- | +| `action` | 
string
| API controller's action | +| `collection` | 
string
| Data collection | +| `controller` | 
string
| API controller | +| `index` | 
string
| Data index | +| `protocol` | 
string
| Network protocol used to modify the document | +| `result` | 
object
| Notification content | +| `room` | 
string
| Subscription channel identifier. Can be used to link a notification to its corresponding subscription | +| `scope` | 
string
| `in`: document enters (or stays) in the scope
number | Timestamp of the event, in Epoch-millis format | +| `type` | 
string
| `document`: Notification type | +| `volatile` | 
object
| Request [volatile data](/core/1/api/essentials/volatile-data/) | + +The `result` object is the notification content, and it has the following structure: + +| Property | Type | Description | +| --------- | ----------------- | --------------------------------------------------------------------------------------- | +| `_id` | 
string
| Document unique ID
object | Message or full document content. Not present if the event is about a document deletion | + +## User + +These notifications represent [user events](/core/1/api/essentials/notifications#user-notification). + +| Property | Type | Description | +| ------------ | ----------------- | ----------------------------------------------------------------------------------------------------- | +| `action` | 
string
| API controller's action | +| `collection` | 
string
| Data collection | +| `controller` | 
string
| API controller | +| `index` | 
string
| Data index | +| `protocol` | 
string
| Network protocol used by the entering/leaving user | +| `result` | 
object
| Notification content | +| `room` | 
string
| Subscription channel identifier. Can be used to link a notification to its corresponding subscription | +| `timestamp` | 
number
| Timestamp of the event, in Epoch-millis format | +| `type` | 
string
| `user`: Notification type | +| `user` | 
string
| `in`: a new user has subscribed to the same filters
object | Request [volatile data](/core/1/api/essentials/volatile-data/) | + +The `result` object is the notification content, and it has the following structure: + +| Property | Type | Description | +| -------- | ----------------- | -------------------------------------------------- | +| `count` | 
number
| Updated users count sharing that same subscription | + +## Server + +These notifications represent [server events](/core/1/api/essentials/notifications#server-notification). + +| Property | Type | Value | +| --------- | ----------------- | ------------------------------------------------------------------ | +| `message` | 
string
| Server message explaining why this notification has been triggered | +| `type` | 
string
| `TokenExpired`: notification type | diff --git a/doc/6/getting-started/index.md b/doc/6/getting-started/index.md new file mode 100644 index 000000000..7ea7b11d6 --- /dev/null +++ b/doc/6/getting-started/index.md @@ -0,0 +1,7 @@ +--- +code: false +type: branch +title: Getting Started +description: Get started with the Javascript SDK +order: 0 +--- diff --git a/doc/6/getting-started/node-js/index.md b/doc/6/getting-started/node-js/index.md new file mode 100644 index 000000000..1c15138d8 --- /dev/null +++ b/doc/6/getting-started/node-js/index.md @@ -0,0 +1,157 @@ +--- +code: false +type: page +title: Node.js +description: Getting started with Kuzzle and Node.js +order: 0 +--- + +# Getting Started with Kuzzle and Node.js + +This tutorial explains you how to use **Kuzzle** with **Node.js** and the **Javascript SDK**. +It will walk you through creating scripts that can **store** documents in Kuzzle and subscribe to **notifications** about document creations. + +You are going to write an application that **stores** documents in Kuzzle Server and subscribe to **real time notifications** for each created document. + +To follow this tutorial, you must have a Kuzzle Server up and running. Follow these instructions if this is not already the case: [Running Kuzzle](/core/1/guides/getting-started/running-kuzzle/). + + +:::info +Having trouble? Get in touch with us on [Gitter](https://gitter.im/kuzzleio/kuzzle)! +::: + +## Explore the SDK + +It's time to get started with the [Kuzzle Javascript SDK](/sdk/js/6). This section, explains you how to store a document and subscribe to notifications in Kuzzle using the Javascript SDK. + +Before proceeding, please make sure your system has **Node.js** version 8 or higher ([download page](https://nodejs.org/en/download/)) installed. + +## Prepare your environment + +Create your playground directory and install the Javascript SDK from the command line using npm: + +```sh +mkdir "kuzzle-playground" +cd "kuzzle-playground" +npm install kuzzle-sdk +``` + +:::info +If you are performing a clean install you might get some `UNMET PEER DEPENDENCY` warnings, these are safe to ignore as they refer to optional dependencies. +::: + +Then, create an `init.js` file and start by adding the code below. +This loads the SDK and connects it to a Kuzzle instance using the WebSocket protocol. + +<<< ./snippets/load-sdk.js + +:::info +Replace 'kuzzle' which is the Kuzzle server hostname with 'localhost' or with the host name where your Kuzzle server is running. +::: + +Next, add a listener to be notified in case of a connection error: + +```js +kuzzle.on('networkError', error => { + console.error('Network Error: ', error); +}); +``` + +Then, connect the client to your Kuzzle server with the `connect()` method, afterwards you have to add the code that will access Kuzzle to create a new index 'nyc-open-data' and a new collection 'yellow-taxi' that you will use to store data later on. + +<<< ./snippets/prepare-db.js + +Your `init.js` file should now look like this: + +<<< ./snippets/init.js + +This code does the following: + +- loads the `Kuzzle SDK` from its NPM package +- creates an instance of the SDK +- connects it to Kuzzle running on `kuzzle` (change the hostname if needed) using WebSocket +- creates the `nyc-open-data` index +- creates the `yellow-taxi` collection (within the `nyc-open-data` index), +- disconnects from Kuzzle after the collection is created or if an error occurs + +Run the code with Node.js: + +```bash +node init.js +``` + +The console should output the following message: + +```bash +nyc-open-data/yellow-taxi ready! +``` + +:::success +Congratulations! You are now ready to say Hello to the World! +::: + +## Create your first "Hello World" document + +Create a `create.js` file with the following code: + +<<< ./snippets/create.js + +This code does the following: + +- creates a new document in the `yellow-taxi` collection, within the `nyc-open-data` index +- logs a success message to the console if everything went fine +- logs an error message if any of the previous actions fails +- disconnects from Kuzzle after the document is created or if an error occurs + +Run the code with Node.js: + +```bash +node create.js +``` + +:::success +You have now successfully stored your first document into Kuzzle. You can now open an [Admin Console](http://console.kuzzle.io) to browse your collection and confirm that your document was saved. +::: + + +## Subscribe to realtime document notifications (pub/sub) + +Kuzzle provides pub/sub features that can be used to trigger real-time notifications based on the state of your data (for a deep-dive on notifications check out the [realtime notifications](/sdk/js/6/essentials/realtime-notifications/) documentation). + +Let's get started. Create a `subscribe.js` file with the following code: + +<<< ./snippets/subscribe.js + +Run the code with Node.js: + +```bash +node subscribe.js +``` + +The `subscribe.js` program is now running endlessly, waiting for notifications about documents matching its filters, specifically documents that have a `license` field equal to `'B'`. + +Now in another terminal, launch the `create.js` file from the previous section. + +```bash +node create.js +``` + +This creates a new document in Kuzzle which, in turn, triggers a [document notification](/core/1/api/essentials/notifications/#documents-changes-messages) sent to the `subscribe.js` program. +Check the `subscribe.js` terminal: a new message is printed everytime a document is created using the `create.js` code. + +```bash +New driver Sirkis with id AWccRe3-DfukVhSzMdUo has B license. +``` + +:::success +Congratulations! You have just set up your first pub/sub communication! +::: + +## Where do we go from here? + +Now that you're more familiar with Kuzzle, dive even deeper to learn how to leverage its full capabilities: + +- discover what this SDK has to offer by browsing other sections of this documentation +- learn how to use [Koncorde](/core/1/guides/cookbooks/realtime-api) to create incredibly fine-grained and blazing-fast subscriptions +- learn how to perform a [basic authentication](/sdk/js/6/controllers/auth/login) +- follow our guide to learn how to [manage users, and how to set up fine-grained access control](/core/1/guides/essentials/security/) diff --git a/doc/6/getting-started/node-js/snippets/create.js b/doc/6/getting-started/node-js/snippets/create.js new file mode 100644 index 000000000..abd761b20 --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/create.js @@ -0,0 +1,39 @@ +// Loads the Kuzzle SDK modules +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client with the WebSocket protocol +// Replace 'kuzzle' with your Kuzzle server hostname (e.g. 'localhost') +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); + +// Adds a listener to detect connection problems +kuzzle.on('networkError', error => { + console.error('Network Error:', error); +}); + +const run = async () => { + try { + // Connects to the Kuzzle server + await kuzzle.connect(); + + // Creates a document + const driver = { + name: 'Sirkis', + birthday: '1959-06-22', + license: 'B' + }; + + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', driver); + console.log('New document successfully created!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; + +run(); diff --git a/doc/6/getting-started/node-js/snippets/create.test.yml b/doc/6/getting-started/node-js/snippets/create.test.yml new file mode 100644 index 000000000..910484f25 --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/create.test.yml @@ -0,0 +1,11 @@ +name: gettingstarted#nodejscreate +description: Creates a document +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: empty +expected: New document successfully created! +sdk: js +version: 6 diff --git a/doc/6/getting-started/node-js/snippets/init.js b/doc/6/getting-started/node-js/snippets/init.js new file mode 100644 index 000000000..fd0a31384 --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/init.js @@ -0,0 +1,37 @@ +// Loads the Kuzzle SDK modules +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client with the WebSocket protocol +// Replace 'kuzzle' with your Kuzzle server hostname (e.g. 'localhost') +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); + +// Adds a listener to detect connection problems +kuzzle.on('networkError', error => { + console.error('Network Error:', error); +}); + +const run = async () => { + try { + // Connects to the Kuzzle server + await kuzzle.connect(); + + // Creates an index + await kuzzle.index.create('nyc-open-data'); + + // Creates a collection + await kuzzle.collection.create('nyc-open-data', 'yellow-taxi'); + + console.log('nyc-open-data/yellow-taxi ready!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; + +run(); diff --git a/doc/6/getting-started/node-js/snippets/init.test.yml b/doc/6/getting-started/node-js/snippets/init.test.yml new file mode 100644 index 000000000..0e76545bc --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/init.test.yml @@ -0,0 +1,9 @@ +name: gettingstarted#nodejsinit +description: Creates an index and a collection +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: empty +expected: nyc-open-data/yellow-taxi ready! +sdk: js +version: 6 diff --git a/doc/6/getting-started/node-js/snippets/load-sdk.js b/doc/6/getting-started/node-js/snippets/load-sdk.js new file mode 100644 index 000000000..ae17a9b0e --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/load-sdk.js @@ -0,0 +1,9 @@ +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Replace 'kuzzle' with your Kuzzle server hostname (e.g. 'localhost') +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); diff --git a/doc/6/getting-started/node-js/snippets/load-sdk.test.yml b/doc/6/getting-started/node-js/snippets/load-sdk.test.yml new file mode 100644 index 000000000..0d32da204 --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/load-sdk.test.yml @@ -0,0 +1,9 @@ +name: gettingstarted#nodejsload +description: Load SDK +hooks: + before: + after: +template: empty +expected: Success +sdk: js +version: 6 diff --git a/doc/6/getting-started/node-js/snippets/prepare-db.js b/doc/6/getting-started/node-js/snippets/prepare-db.js new file mode 100644 index 000000000..2fb9b8410 --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/prepare-db.js @@ -0,0 +1,20 @@ +const run = async () => { + try { + // Connects to the Kuzzle server + await kuzzle.connect(); + + // Creates an index + await kuzzle.index.create('nyc-open-data'); + + // Creates a collection + await kuzzle.collection.create('nyc-open-data', 'yellow-taxi'); + + console.log('nyc-open-data/yellow-taxi ready!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; + +run(); diff --git a/doc/6/getting-started/node-js/snippets/prepare-db.test.yml b/doc/6/getting-started/node-js/snippets/prepare-db.test.yml new file mode 100644 index 000000000..e51b6f7ce --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/prepare-db.test.yml @@ -0,0 +1,9 @@ +name: gettingstarted#nodejspreparedb +description: Prepare database +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: blank +expected: nyc-open-data/yellow-taxi ready! +sdk: js +version: 6 diff --git a/doc/6/getting-started/node-js/snippets/subscribe.js b/doc/6/getting-started/node-js/snippets/subscribe.js new file mode 100644 index 000000000..f85d66357 --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/subscribe.js @@ -0,0 +1,51 @@ +// Loads the Kuzzle SDK modules +const { + Kuzzle, + WebSocket +} = require('kuzzle-sdk'); + +// Instantiates a Kuzzle client with the WebSocket protocol +// Replace 'kuzzle' with your Kuzzle server hostname (e.g. 'localhost') +const kuzzle = new Kuzzle( + new WebSocket('kuzzle') +); + +// Adds a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error('Network Error:', error); +}); + +const run = async () => { + try { + // Connects to the Kuzzle server + await kuzzle.connect(); + + // Defines a filter + const filter = { + equals: { license: 'B' } + }; + + // Defines a callback invoked each time a notification is received + const callback = (notification) => { + + if (notification.type === 'document' && notification.action === 'create') { + const { + _source: driver, + _id: driverId + } = notification.result; + + console.log(`New driver ${driver.name} with id ${driverId} has B license.`); + kuzzle.disconnect(); + } + }; + + // Subscribes to document notifications using the above filter + await kuzzle.realtime.subscribe('nyc-open-data', 'yellow-taxi', filter, callback); + + console.log('Successfully subscribed to document notifications!'); + } catch (error) { + console.error(error.message); + } +}; + +run(); diff --git a/doc/6/getting-started/node-js/snippets/subscribe.test.yml b/doc/6/getting-started/node-js/snippets/subscribe.test.yml new file mode 100644 index 000000000..5e6720558 --- /dev/null +++ b/doc/6/getting-started/node-js/snippets/subscribe.test.yml @@ -0,0 +1,11 @@ +name: gettingstarted#nodejssubscribe +description: Subscribes to document notifications +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: empty-realtime +expected: Successfully subscribed to document notifications! +sdk: js +version: 6 diff --git a/doc/6/getting-started/raw-web/index.md b/doc/6/getting-started/raw-web/index.md new file mode 100644 index 000000000..bee031566 --- /dev/null +++ b/doc/6/getting-started/raw-web/index.md @@ -0,0 +1,168 @@ +--- +code: false +type: page +title: Browser (Vanilla) +description: Getting started with Kuzzle in the browser +order: 100 +--- + +# Getting Started with Kuzzle in the browser + +This tutorial explains how to use **Kuzzle** with the **Javascript SDK** in a **browser**. + +To follow this tutorial, you must have a Kuzzle Server up and running (you'll need to know the hostname of the machine running it). If this is not already the case, take a look at [how to run Kuzzle](/core/1/guides/getting-started/running-kuzzle/). + +Before proceeding, make sure your system has **Node.js** version 8 or higher ([download page](https://nodejs.org/en/download/)) installed. + +In this tutorial, you'll learn how to **store** a document and **subscribe** to notifications in Kuzzle using the Javascript SDK. + +:::info +Having trouble? Get in touch with us on [Gitter](https://gitter.im/kuzzleio/kuzzle)! +::: + +## Prepare your environment + +Create your playground directory: + +```sh +mkdir "kuzzle-playground" +cd "kuzzle-playground" +``` + +:::info +If you are performing a clean install you might get some `UNMET PEER DEPENDENCY` warnings, these are safe to ignore as they refer to optional dependencies. +::: + +Then, create an `index.html` file with the following structure: + +```html + + + + + + Kuzzle SDK Playground + + + + + + + + +``` + +:::info +If you are using Internet Explorer (not Edge), you are responsible of installing a Promise polyfill, which enables IE to support +Javascript [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). +Our advice is to use [Bluebird](http://bluebirdjs.com/docs/getting-started.html), as shown in the code example above (refer to the commented lines in the `head` tag). +::: + +Then, add the code below in the `body` tag. +This loads the SDK and connects it to a Kuzzle instance using the WebSocket protocol. If an error occurs, it is displayed +in the console. Once the connection is established, a success message is displayed in the console. + +<<< ./snippets/load-sdk.html + +:::info +Replace `kuzzle` with localhost or with the host name where your Kuzzle server is running. +::: + +Now you have to add the code that will access Kuzzle to create a new index `nyc-open-data` and a new collection `yellow-taxi` +that you will use to store data later on. Make sure the code inside your `body` tag looks like the following: + +<<< ./snippets/prepare-db.html + +Now, let's take a look at what your script is doing: + +- creates an instance of the SDK, +- connects it to Kuzzle running on `kuzzle` (change the hostname if needed) using WebSocket, +- creates the `nyc-open-data` index, +- creates the `yellow-taxi` collection (within the `nyc-open-data` index), +- disconnects from Kuzzle after the collection is created, +- displays an error whenever something goes wrong. + +Run this code by opening the `index.html` file in your favorite browser. +The console should output the following message: + +``` +Successfully connected to Kuzzle +nyc-open-data/yellow-taxi ready! +``` + +:::success +Congratulations! You are now ready to say Hello to the World! +::: + +:::info +If you reload the page, you should see an error in the console. This is OK, since Kuzzle is just refusing to create +the `nyc-open-data` index as it already exists. +::: + +## Create your first "Hello World" document + +Create a `create.html` file with the same structure as `index.html` (see above). +And, right like before, add some code to the `body` tag: + +<<< ./snippets/create.html + +This code does the following: + +- creates an instance of the SDK, +- connects it to Kuzzle running on `kuzzle` (change the hostname if needed) using WebSocket, +- creates a new document in the `yellow-taxi` collection, within the `nyc-open-data` index +- logs a success message to the console if everything went fine +- logs an error message if any of the previous actions fails +- disconnects from Kuzzle after the document is created or if an error occurs + +Run this code by opening the `create.html` file in your favorite browser. +The console should output the following message: + +``` +Successfully connected to Kuzzle +New document successfully created! +``` + +:::success +You have now successfully stored your first document into Kuzzle. Check our [Admin Console Guide](/core/1/guides/essentials/admin-console/) to see how to browse your collection and confirm that your document was saved. +::: + + +## Subscribe to realtime document notifications (pub/sub) + +Kuzzle provides pub/sub features that can be used to trigger real-time notifications based on the state of your data (for a deep-dive on notifications check out the [realtime notifications](/sdk/js/6/essentials/realtime-notifications/) documentation). + +Let's get started. Create a `subscribe.html` file (same structure as above) with the following code in the `body` tag: + +<<< ./snippets/subscribe.html + +Run this code by opening the `subscribe.html` file in a new tab, leaving the previous one (showing `create.html`) open. +The console should output the following message: + +``` +Successfully connected to Kuzzle +Successfully subscribed to document notifications! +``` + +The code in the `subscribe.html` page is now running endlessly, waiting for notifications about documents matching its filters, specifically documents that have a `license` field equal to `'B'`. + +Now go back to the other tab and reload `create.html`. + +This creates a new document in Kuzzle which, in turn, triggers a [document notification](/core/1/api/essentials/notifications/#documents-changes-messages) sent to the `subscribe.html` tab. Check the `subscribe.html` tab: a new message is printed everytime a document is created using the `create.html` code. + +``` +New driver Sirkis with id AWccRe3-DfukVhSzMdUo has B license. +``` + +:::success +Congratulations! You have just set up your first pub/sub communication! +::: + +## Where do we go from here? + +Now that you're more familiar with Kuzzle, dive even deeper to learn how to leverage its full capabilities: + +- discover what this SDK has to offer by browsing other sections of this documentation +- learn how to use [Koncorde](/core/1/guides/cookbooks/realtime-api) to create incredibly fine-grained and blazing-fast subscriptions +- learn how to perform a [basic authentication](/sdk/js/6/controllers/auth/login) +- follow our guide to learn how to [manage users, and how to set up fine-grained access control](/core/1/guides/essentials/security/) diff --git a/doc/6/getting-started/raw-web/snippets/create.html b/doc/6/getting-started/raw-web/snippets/create.html new file mode 100644 index 000000000..70aee4f09 --- /dev/null +++ b/doc/6/getting-started/raw-web/snippets/create.html @@ -0,0 +1,31 @@ + diff --git a/doc/6/getting-started/raw-web/snippets/create.test.yml b/doc/6/getting-started/raw-web/snippets/create.test.yml new file mode 100644 index 000000000..557868de8 --- /dev/null +++ b/doc/6/getting-started/raw-web/snippets/create.test.yml @@ -0,0 +1,12 @@ +name: gettingstarted#browservanillacreate +description: Create a document +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: default +expected: New document successfully created +sdk: js +version: 6 +runner: web diff --git a/doc/6/getting-started/raw-web/snippets/load-sdk.html b/doc/6/getting-started/raw-web/snippets/load-sdk.html new file mode 100644 index 000000000..10d2477d1 --- /dev/null +++ b/doc/6/getting-started/raw-web/snippets/load-sdk.html @@ -0,0 +1,14 @@ + \ No newline at end of file diff --git a/doc/6/getting-started/raw-web/snippets/load-sdk.test.yml b/doc/6/getting-started/raw-web/snippets/load-sdk.test.yml new file mode 100644 index 000000000..c17ef17d8 --- /dev/null +++ b/doc/6/getting-started/raw-web/snippets/load-sdk.test.yml @@ -0,0 +1,10 @@ +name: gettingstarted#browservanillaconnect +description: Connect to Kuzzle +hooks: + before: + after: +template: default +expected: Successfully connected to Kuzzle +sdk: js +version: 6 +runner: web diff --git a/doc/6/getting-started/raw-web/snippets/prepare-db.html b/doc/6/getting-started/raw-web/snippets/prepare-db.html new file mode 100644 index 000000000..c392a86b4 --- /dev/null +++ b/doc/6/getting-started/raw-web/snippets/prepare-db.html @@ -0,0 +1,29 @@ + \ No newline at end of file diff --git a/doc/6/getting-started/raw-web/snippets/prepare-db.test.yml b/doc/6/getting-started/raw-web/snippets/prepare-db.test.yml new file mode 100644 index 000000000..3ac1c5a75 --- /dev/null +++ b/doc/6/getting-started/raw-web/snippets/prepare-db.test.yml @@ -0,0 +1,10 @@ +name: gettingstarted#browservanillaprepare +description: Prepare the database +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: default +expected: nyc-open-data/yellow-taxi ready +sdk: js +version: 6 +runner: web diff --git a/doc/6/getting-started/raw-web/snippets/subscribe.html b/doc/6/getting-started/raw-web/snippets/subscribe.html new file mode 100644 index 000000000..ec6c858ab --- /dev/null +++ b/doc/6/getting-started/raw-web/snippets/subscribe.html @@ -0,0 +1,32 @@ + \ No newline at end of file diff --git a/doc/6/getting-started/raw-web/snippets/subscribe.test.yml b/doc/6/getting-started/raw-web/snippets/subscribe.test.yml new file mode 100644 index 000000000..2fad572cd --- /dev/null +++ b/doc/6/getting-started/raw-web/snippets/subscribe.test.yml @@ -0,0 +1,12 @@ +name: gettingstarted#browservanillasubscribe +description: Subscribe to notifications +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: default +expected: Successfully subscribed to document notifications +sdk: js +version: 6 +runner: web diff --git a/doc/6/getting-started/webpack/index.md b/doc/6/getting-started/webpack/index.md new file mode 100644 index 000000000..aa88ebfc9 --- /dev/null +++ b/doc/6/getting-started/webpack/index.md @@ -0,0 +1,212 @@ +--- +type: page +code: false +title: Webpack +description: Getting started with Kuzzle and Webpack +order: 200 +--- + +# Getting Started with Kuzzle and Webpack + +In this tutorial you will learn how to install, run and use **Kuzzle** with the **Javascript SDK** in the browser using **Webpack**. +We will walk you through creating scripts that can **store** documents in Kuzzle and subscribe to **notifications** for each new document created. + +:::info +Having trouble? Get in touch with us on [Gitter](https://gitter.im/kuzzleio/kuzzle)! +::: + +## Running Kuzzle + +Before going through this tutorial, you should have a Kuzzle server running. Please refer to the [Running Kuzzle Tutorial](/core/1/guides/getting-started/running-kuzzle/) if you don't have one yet. + +## Fun with the SDK + +It's time to play with the [Kuzzle Javscript SDK](/sdk/js/6). In this section, we will store a document and subscribe to notifications in Kuzzle using the Javascript SDK in your browser. + +Before proceeding, please make sure your system has **Node.js** version 8 or higher ([instructions here](https://nodejs.org/en/download/)) installed. + +## Including the Kuzzle SDK in a Webpack project + +::: info +This section explains how to use the Kuzzle SDK within an existing Webpack project. +If you don't have your project up and running yet and want to learn how to leverage Webpack to build it, please refer to +the [official Webpack Getting Started page](https://webpack.js.org/guides/getting-started/). +::: + +In your terminal, go to the root of your front-end project using Webpack and type + +```bash +npm install kuzzle-sdk +``` + +:::info +If you are performing a clean install you might see some `UNMET PEER DEPENDENCY` warnings, these are safe to ignore as they refer to optional dependencies. +::: + +Then, create a `init-kuzzle.js` file and start by adding the code below. This will load the Kuzzle Javascript SDK: + +<<< ./snippets/init-kuzzle.js:1 + +Next, we instantiate a client that will connect to Kuzzle via WebSocket. If Kuzzle is not running on localhost, replace it with the corresponding server name or IP address. + +<<< ./snippets/init-kuzzle.js:2 + +Next we add a listener to be notified in case of a connection error: + +<<< ./snippets/init-kuzzle.js:3 + +Then we have to connect our web app to the Kuzzle server with the `connect()` method. + +```js +const run = async () => { + try { + // Connect to Kuzzle server + await kuzzle.connect(); + // Some more things will go here... + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; +``` + +Finally, we will create a new index `nyc-open-data` and a new collection +`yellow-taxi` that we will use to store data later on. + +<<< ./snippets/init-kuzzle.js:4 + +Your `kuzzle-init.js` file should now look like this: + +<<< ./snippets/init-kuzzle.js + +This code does the following: + +- loads the `kuzzle-sdk` from its NPM package +- creates an instance of the SDK +- connects it to Kuzzle running on `localhost` with the `WebSocket` protocol +- creates the `nyc-open-data` index +- creates the `yellow-taxi` collection (within the `nyc-open-data` index), +- disconnects from Kuzzle after the collection is created or if an error occurs + +Now, to have your script up and running, require it somewhere in your application +(e.g. your main entry point) and launch it. + +```js +require('../path/to/init-kuzzle.js'); +``` + +Your console should output the following message: + +``` +nyc-open-data/yellow-taxi ready! +``` + +::: success +Congratulations! You are now ready to say Hello to the World! +::: + +::: info +Having trouble? Get in touch with us on [Gitter!](https://gitter.im/kuzzleio/kuzzle) We're happy to help. +::: + +## Create your first document + +Create a `create.js` file with following code: + +<<< ./snippets/create.js + +This code does the following: + +- creates a new document in `nyc-open-data` within the `yellow-taxi` index +- logs a success message to the console if everything went fine +- logs an error message if any of the previous actions failed +- disconnects from Kuzzle after the document is created or if an error occurs + +To activate this code, create a button somewhere in your page like the following + +```html + +``` + +Then, associate it to the `create` function by adding this code to your application + +```js +const create = require('../path/to/create.js'); + +// This is the most "vanilla" way to call a function in reaction to a click, +// if you're using a front-end framework like Vuejs, React or jQuery, feel free +// to follow any convenience method it provides for this purpose. +document.querySelector('#create-document-btn').addListener('click', event => { + create(); +}); +``` + +Now, click the button and check your console for a message like the following: + +```bash +New document successfully created! +``` + +::: success +You have now successfully stored your first document into Kuzzle. Click +[here](/core/1/guides/essentials/admin-console/) to see how you can use the +[**Kuzzle Admin Console**](http://console.kuzzle.io/) to browse your collection and +confirm that your document was saved. +::: + +::: info +Having trouble? Get in touch with us on [Gitter!](https://gitter.im/kuzzleio/kuzzle) We're happy to help. +::: + +## Subscribe to realtime document notifications (pub/sub) + +Kuzzle provides pub/sub features that can be used to trigger real-time notifications based on the state of your data (for a deep-dive on notifications check out the [realtime notifications](/sdk/js/6/essentials/realtime-notifications/) documentation). + +Let's get started. Create a `subscribe.js` file with following code: + +<<< ./snippets/subscribe.js + +This code does the following: + +- loads the `Kuzzle SDK` from its NPM package +- creates an instance of the SDK +- connects it to Kuzzle running on `localhost` with the `websocket` protocol +- defines a filter for the subscription to be done later (drivers with "B" license) +- defines a callback that will be called whenever a notification is received from Kuzzle (print driver name to console) +- subscribes for notifications on the `yellow-taxi` collection + +You can execute this code in the same page as before or in another page of your app. Whatever option you choose, to +execute the code, you just need to require it in your page + +```js +require('../path/to/subscribe.js'); +``` + +From now on, whenever you click the button we created before, Kuzzle will send a notification to the page containing +the subscription to the `yellow-taxi` collection. In the console corresponding to this page, you should see the following message: + +```bash +New driver Sirkis with id has B license. +``` + +In place of `` you'll see the ID that Kuzzle automatically generated for the document. + +::: success +Congratulations! You have just choreographed your first pub/sub pattern! +::: + +::: info +Having trouble? Get in touch with us on [Gitter!](https://gitter.im/kuzzleio/kuzzle) We're happy to help. +::: + +## Where do we go from here? + +Now that you're more familiar with Kuzzle, dive even deeper to learn how to leverage its full capabilities: + +- take a look at the [SDK Reference](/sdk/js/6) +- learn how to use [Koncorde](/core/1/guides/cookbooks/realtime-api) to create incredibly fine-grained and blazing-fast subscriptions +- follow our guide to learn how to implement [basic authentication](/core/1/guides/essentials/user-authentication/#local-strategy) +- follow our guide to learn how to implement [manage users and setup fine-grained access control](/core/1/guides/essentials/security/) diff --git a/doc/6/getting-started/webpack/snippets/create.js b/doc/6/getting-started/webpack/snippets/create.js new file mode 100644 index 000000000..fe66ca6b5 --- /dev/null +++ b/doc/6/getting-started/webpack/snippets/create.js @@ -0,0 +1,33 @@ +// load the Kuzzle SDK module +import { Kuzzle, WebSocket } from 'kuzzle-sdk'; + +// instantiate a Kuzzle client +const kuzzle = new Kuzzle(new WebSocket('kuzzle')); + +// add a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error}`); +}); + +const doIt = async () => { + try { + // Connect to Kuzzle server + await kuzzle.connect(); + + // Create your document + const driver = { + name: 'Sirkis', + birthday: '1959-06-22', + license: 'B' + }; + + await kuzzle.document.create('nyc-open-data', 'yellow-taxi', driver); + console.log('New document successfully created!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; + +export default doIt; diff --git a/doc/6/getting-started/webpack/snippets/create.test.yml b/doc/6/getting-started/webpack/snippets/create.test.yml new file mode 100644 index 000000000..fb4561210 --- /dev/null +++ b/doc/6/getting-started/webpack/snippets/create.test.yml @@ -0,0 +1,13 @@ +name: gettingstarted#webpackcreate +description: Creates a document +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: doIt +expected: New document successfully created! + +runner: webpack +sdk: js +version: 6 diff --git a/doc/6/getting-started/webpack/snippets/init-kuzzle.js b/doc/6/getting-started/webpack/snippets/init-kuzzle.js new file mode 100644 index 000000000..dd8476b40 --- /dev/null +++ b/doc/6/getting-started/webpack/snippets/init-kuzzle.js @@ -0,0 +1,38 @@ +// load the Kuzzle SDK module +/* snippet:start:1 */ +import { Kuzzle, WebSocket } from 'kuzzle-sdk'; +/* snippet:end */ + +// instantiate a Kuzzle client +/* snippet:start:2 */ +const kuzzle = new Kuzzle(new WebSocket('kuzzle')); +/* snippet:end */ + +// add a listener to detect any connection problems +/* snippet:start:3 */ +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error}`); +}); +/* snippet:end */ + +/* snippet:start:4 */ +const run = async () => { + try { + // Connect to Kuzzle server + await kuzzle.connect(); + + // Create an index + await kuzzle.index.create('nyc-open-data'); + + // Create a collection + await kuzzle.collection.create('nyc-open-data', 'yellow-taxi'); + console.log('nyc-open-data/yellow-taxi ready!'); + } catch (error) { + console.error(error.message); + } finally { + kuzzle.disconnect(); + } +}; +/* snippet:end */ + +run(); diff --git a/doc/6/getting-started/webpack/snippets/init-kuzzle.test.yml b/doc/6/getting-started/webpack/snippets/init-kuzzle.test.yml new file mode 100644 index 000000000..cd2ff4589 --- /dev/null +++ b/doc/6/getting-started/webpack/snippets/init-kuzzle.test.yml @@ -0,0 +1,10 @@ +name: gettingstarted#webpackinitkuzzle +description: Creates an index and a collection +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: empty +expected: nyc-open-data/yellow-taxi ready! +sdk: js +version: 6 +runner: webpack diff --git a/doc/6/getting-started/webpack/snippets/subscribe.js b/doc/6/getting-started/webpack/snippets/subscribe.js new file mode 100644 index 000000000..892c99bcb --- /dev/null +++ b/doc/6/getting-started/webpack/snippets/subscribe.js @@ -0,0 +1,49 @@ +// load the Kuzzle SDK module +import { Kuzzle, WebSocket } from 'kuzzle-sdk'; + +// instantiate a Kuzzle client +const kuzzle = new Kuzzle(new WebSocket('kuzzle')); + +// add a listener to detect any connection problems +kuzzle.on('networkError', error => { + console.error(`Network Error: ${error}`); +}); + +const doIt = async () => { + try { + // Connect to Kuzzle server + await kuzzle.connect(); + + // Define a filter + const filter = { + equals: { license: 'B' } + }; + + // Define a callback + const callback = notification => { + if ( + notification.type === 'document' && + notification.action === 'create' + ) { + const driver = notification.result._source; + const driverId = notification.result._id; + console.log( + `New driver ${driver.name} with id ${driverId} has B license.` + ); + } + }; + + // Subscribes to document notifications with our filter + await kuzzle.realtime.subscribe( + 'nyc-open-data', + 'yellow-taxi', + filter, + callback + ); + console.log('Successfully subscribed to document notifications!'); + } catch (error) { + console.error(error.message); + } +}; + +doIt(); diff --git a/doc/6/getting-started/webpack/snippets/subscribe.test.yml b/doc/6/getting-started/webpack/snippets/subscribe.test.yml new file mode 100644 index 000000000..f62f51a44 --- /dev/null +++ b/doc/6/getting-started/webpack/snippets/subscribe.test.yml @@ -0,0 +1,14 @@ +name: gettingstarted#webpacksubscribe +description: Subscribes to document notifications +hooks: + before: | + curl -XPOST kuzzle:7512/nyc-open-data/_create + curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi + after: +template: createDocumentAfterSnippet +expected: + - Successfully subscribed to document notifications! + - New driver Sirkis with id +sdk: js +version: 6 +runner: webpack diff --git a/doc/6/index.md b/doc/6/index.md new file mode 100644 index 000000000..1f7b5ba97 --- /dev/null +++ b/doc/6/index.md @@ -0,0 +1,7 @@ +--- +code: false +type: root +order: 0 +title: Javascript SDK v6.x +description: Javascript SDK v6.x +--- diff --git a/doc/6/protocols/http/constructor/index.md b/doc/6/protocols/http/constructor/index.md new file mode 100644 index 000000000..24a46550c --- /dev/null +++ b/doc/6/protocols/http/constructor/index.md @@ -0,0 +1,41 @@ +--- +code: true +type: page +title: constructor +description: Creates a new Http protocol +order: 50 +--- + +# Constructor + +Use this constructor to create a new instance of the `Http` protocol with specific options. + +## Arguments + +```js +Http(host, [options]); +``` + +
+ +| Argument | Type | Description | +| --------- | ----------------- | ---------------------------- | +| `host` | 
string
| Kuzzle server hostname or IP | +| `options` | 
object
| Http connection options | + +### options + +Http protocol connection options. + +| Property | Type
(default) | Description | +| --------------- | -------------------------------- | ----------------------------------- | +| `port` | 
number

(`7512`) | Kuzzle server port | +| `sslConnection` | 
boolean

(`false`) | Use SSL to connect to Kuzzle server | + +## Return + +A `Http` protocol instance. + +## Usage + +<<< ./snippets/constructor.js diff --git a/doc/6/protocols/http/constructor/snippets/constructor.js b/doc/6/protocols/http/constructor/snippets/constructor.js new file mode 100644 index 000000000..073ebabdd --- /dev/null +++ b/doc/6/protocols/http/constructor/snippets/constructor.js @@ -0,0 +1,16 @@ +// Loads the Http protocol +const + { + Kuzzle, + Http + } = require('kuzzle-sdk'); + +const options = { + sslConnection: false +}; + +// Instantiates the Http protocol +const httpProtocol = new Http('kuzzle', options); + +// Use it with Kuzzle +const kuzzle = new Kuzzle(httpProtocol); diff --git a/doc/6/protocols/http/constructor/snippets/constructor.test.yml b/doc/6/protocols/http/constructor/snippets/constructor.test.yml new file mode 100644 index 000000000..585b32c5a --- /dev/null +++ b/doc/6/protocols/http/constructor/snippets/constructor.test.yml @@ -0,0 +1,10 @@ +--- +name: http#constructor +description: Creates a new Http instance +hooks: + before: + after: +template: empty +expected: Success +sdk: js +version: 6 diff --git a/doc/6/protocols/http/index.md b/doc/6/protocols/http/index.md new file mode 100644 index 000000000..7d3ae6f0e --- /dev/null +++ b/doc/6/protocols/http/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: Http +description: Http protocol documentation +order: 600 +--- diff --git a/doc/6/protocols/http/introduction/index.md b/doc/6/protocols/http/introduction/index.md new file mode 100644 index 000000000..0bb636705 --- /dev/null +++ b/doc/6/protocols/http/introduction/index.md @@ -0,0 +1,17 @@ +--- +code: false +type: page +title: Introduction +description: Http protocol implementation +order: 0 +--- + +# Http + +The Http protocol can be used by an instance of the SDK to communicate with your Kuzzle server. + +:::info +This protocol does not allow to use the [real-time notifications](/sdk/js/6/essentials/realtime-notifications/). + +If you need real-time features, then you have to use either [WebSocket](/sdk/js/6/protocols/websocket) or [SocketIO](/sdk/js/6/protocols/socketio) protocols. +::: diff --git a/doc/6/protocols/http/properties/index.md b/doc/6/protocols/http/properties/index.md new file mode 100644 index 000000000..e280f5787 --- /dev/null +++ b/doc/6/protocols/http/properties/index.md @@ -0,0 +1,19 @@ +--- +code: false +type: page +title: Properties +description: Http class properties +order: 10 +--- + + +# Properties + +| Property name | Type | Description | +| -------------------- | -------- | ---------------------| +| `connected` | 
boolean
| Always returns `true` | +| `host` | 
string
| Kuzzle server host | +| `http` | 
object
| Returns a list of available routes | +| `port` | 
number
| Kuzzle server port | +| `protocol` | 
string
| `https` or `http` | +| `ssl` | 
boolean
| `true` if ssl is active | diff --git a/doc/6/protocols/index.md b/doc/6/protocols/index.md new file mode 100644 index 000000000..a6a409d8a --- /dev/null +++ b/doc/6/protocols/index.md @@ -0,0 +1,7 @@ +--- +code: false +type: branch +order: 300 +title: Protocols +description: Javascript SDK v6.x protocols +--- diff --git a/doc/6/protocols/socketio/constructor/index.md b/doc/6/protocols/socketio/constructor/index.md new file mode 100644 index 000000000..fca54a645 --- /dev/null +++ b/doc/6/protocols/socketio/constructor/index.md @@ -0,0 +1,43 @@ +--- +code: true +type: page +title: constructor +description: Creates a new SocketIO protocol +order: 50 +--- + +# Constructor + +Use this constructor to create a new instance of the `SocketIO` protocol with specific options. + +## Arguments + +```js +SocketIO(host, [options]); +``` + +
+ +| Argument | Type | Description | +| --------- | ----------------- | ---------------------------- | +| `host` | 
string
| Kuzzle server hostname or IP | +| `options` | 
object
| SocketIO connection options | + +### options + +SocketIO protocol connection options. + +| Property | Type
(default) | Description | +| ------------------- | -------------------------------- | -------------------------------------------------------------- | +| `port` | 
number

(`7512`) | Kuzzle server port | +| `sslConnection` | 
boolean

(`false`) | Use SSL to connect to Kuzzle server | +| `autoReconnect` | 
boolean

(`true`) | Automatically reconnect to kuzzle after a `disconnected` event | +| `reconnectionDelay` | 
number

(`1000`) | Number of milliseconds between reconnection attempts | + +## Return + +A `SocketIO` protocol instance. + +## Usage + +<<< ./snippets/constructor.js diff --git a/doc/6/protocols/socketio/constructor/snippets/constructor.js b/doc/6/protocols/socketio/constructor/snippets/constructor.js new file mode 100644 index 000000000..ff5f68f10 --- /dev/null +++ b/doc/6/protocols/socketio/constructor/snippets/constructor.js @@ -0,0 +1,16 @@ +// Loads the SocketIO protocol +const + { + Kuzzle, + SocketIO + } = require('kuzzle-sdk'); + +const options = { + autoReconnect: false +}; + +// Instantiates the SocketIO protocol +const socketIOProtocol = new SocketIO('kuzzle', options); + +// Use it with Kuzzle +const kuzzle = new Kuzzle(socketIOProtocol); diff --git a/doc/6/protocols/socketio/constructor/snippets/constructor.test.yml b/doc/6/protocols/socketio/constructor/snippets/constructor.test.yml new file mode 100644 index 000000000..f8b638ee1 --- /dev/null +++ b/doc/6/protocols/socketio/constructor/snippets/constructor.test.yml @@ -0,0 +1,10 @@ +--- +name: socketio#constructor +description: Creates a new SocketIO instance +hooks: + before: + after: +template: empty +expected: Success +sdk: js +version: 6 diff --git a/doc/6/protocols/socketio/index.md b/doc/6/protocols/socketio/index.md new file mode 100644 index 000000000..44ea1ab0d --- /dev/null +++ b/doc/6/protocols/socketio/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: SocketIO +description: SocketIO protocol documentation +order: 600 +--- diff --git a/doc/6/protocols/socketio/introduction/index.md b/doc/6/protocols/socketio/introduction/index.md new file mode 100644 index 000000000..58717f7ad --- /dev/null +++ b/doc/6/protocols/socketio/introduction/index.md @@ -0,0 +1,16 @@ +--- +code: false +type: page +title: Introduction +description: SocketIO protocol implementation +order: 0 +--- + +# SocketIO + +The SocketIO protocol can be used by an instance of the SDK to communicate with your Kuzzle server. +This protocol allows you to use all the features of Kuzzle, including [real-time notifications](/sdk/js/6/essentials/realtime-notifications/). + +:::info +The SocketIO protocol is used for WebSocket compatibility with older browsers. It is preferable to use the [WebSocket](/sdk/js/6/protocols/websocket) protocol when possible. +::: diff --git a/doc/6/protocols/socketio/properties/index.md b/doc/6/protocols/socketio/properties/index.md new file mode 100644 index 000000000..42aeefe36 --- /dev/null +++ b/doc/6/protocols/socketio/properties/index.md @@ -0,0 +1,22 @@ +--- +code: false +type: page +title: Properties +description: SocketIO class properties +order: 10 +--- + +# Properties + +| Property name | Type | Description | +| -------------------- | -------- | ---------------------| +| `autoReconnect` | 
boolean
| Automatically reconnects after a connection loss | +| `connected` | 
boolean
| Returns `true` if the socket is open | +| `host` | 
string
| Kuzzle server host | +| `port` | 
number
| Kuzzle server port | +| `reconnectionDelay` | 
number
| Number of milliseconds between reconnection attempts | +| `ssl` | 
boolean
| `true` if ssl is active | + +::: info +Updates to `autoReconnect` and `reconnectionDelay` properties will only take effect on the next `connect` call. +::: diff --git a/doc/6/protocols/websocket/constructor/index.md b/doc/6/protocols/websocket/constructor/index.md new file mode 100644 index 000000000..736df3deb --- /dev/null +++ b/doc/6/protocols/websocket/constructor/index.md @@ -0,0 +1,44 @@ +--- +code: true +type: page +title: constructor +description: Creates a new WebSocket protocol +order: 50 +--- + +# Constructor + +This constructor creates a new WebSocket connection, using the specified options. + +## Arguments + +```js +WebSocket(host, [options]); +``` + +
+ +| Argument | Type | Description | +| --------- | ----------------- | ---------------------------- | +| `host` | 
string
| Kuzzle server hostname or IP | +| `options` | 
object
| WebSocket connection options | + +### options + +WebSocket protocol connection options. + +| Property | Type
(default) | Description | +| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- | +| `autoReconnect` | 
boolean

(`true`) | Automatically reconnect to kuzzle after a `disconnected` event | +| `port` | 
number

(`7512`) | Kuzzle server port | +| `headers` | 
object
(`{}`) | Connection HTTP headers (e.g. origin, subprotocols, ...)
**(Not supported by browsers)** | +| `reconnectionDelay` | 
number

(`1000`) | Number of milliseconds between reconnection attempts | +| `sslConnection` | 
boolean

(`false`) | Use SSL to connect to Kuzzle server | + +## Return + +A `WebSocket` protocol instance. + +## Usage + +<<< ./snippets/constructor.js diff --git a/doc/6/protocols/websocket/constructor/snippets/constructor.js b/doc/6/protocols/websocket/constructor/snippets/constructor.js new file mode 100644 index 000000000..17fc0cd26 --- /dev/null +++ b/doc/6/protocols/websocket/constructor/snippets/constructor.js @@ -0,0 +1,16 @@ +// Loads the WebSocket protocol +const + { + Kuzzle, + WebSocket + } = require('kuzzle-sdk'); + +const options = { + autoReconnect: false +}; + +// Instantiates the websocket protocol +const websocketProtocol = new WebSocket('kuzzle', options); + +// Use it with Kuzzle +const kuzzle = new Kuzzle(websocketProtocol); diff --git a/doc/6/protocols/websocket/constructor/snippets/constructor.test.yml b/doc/6/protocols/websocket/constructor/snippets/constructor.test.yml new file mode 100644 index 000000000..9f49ef71a --- /dev/null +++ b/doc/6/protocols/websocket/constructor/snippets/constructor.test.yml @@ -0,0 +1,10 @@ +--- +name: websocket#constructor +description: Creates a new WebSocket instance +hooks: + before: + after: +template: empty +expected: Success +sdk: js +version: 6 diff --git a/doc/6/protocols/websocket/index.md b/doc/6/protocols/websocket/index.md new file mode 100644 index 000000000..e57f9b855 --- /dev/null +++ b/doc/6/protocols/websocket/index.md @@ -0,0 +1,7 @@ +--- +code: true +type: branch +title: WebSocket +description: WebSocket protocol documentation +order: 600 +--- diff --git a/doc/6/protocols/websocket/introduction/index.md b/doc/6/protocols/websocket/introduction/index.md new file mode 100644 index 000000000..1757128cc --- /dev/null +++ b/doc/6/protocols/websocket/introduction/index.md @@ -0,0 +1,15 @@ +--- +code: false +type: page +title: Introduction +description: Websocket protocol implementation +order: 0 +--- + +# WebSocket + +Inherits from: [KuzzleEventEmitter](/sdk/js/6/core-classes/kuzzle-event-emitter) + +The WebSocket protocol can be used by an instance of the SDK to communicate with your Kuzzle server. + +This protocol allows you to use all the features of Kuzzle, including [real-time notifications](/sdk/js/6/essentials/realtime-notifications/). diff --git a/doc/6/protocols/websocket/properties/index.md b/doc/6/protocols/websocket/properties/index.md new file mode 100644 index 000000000..6b20dc9fb --- /dev/null +++ b/doc/6/protocols/websocket/properties/index.md @@ -0,0 +1,22 @@ +--- +code: false +type: page +title: Properties +description: Websocket class properties +order: 10 +--- + +# Properties + +| Property name | Type | Description | +| -------------------- | -------- | ---------------------| +| `autoReconnect` | 
boolean
| Automatically reconnect after a connection loss | +| `connected` | 
boolean
| Returns `true` if the socket is open | +| `host` | 
string
| Kuzzle server host | +| `reconnectionDelay` | 
number
| Number of milliseconds between reconnection attempts | +| `port` | 
number
| Kuzzle server port | +| `ssl` | 
boolean
| `true` if ssl is active | + +::: info +Updates to `autoReconnect` and `reconnectionDelay` properties will only take effect on the next `connect` call. +::: \ No newline at end of file diff --git a/package.json b/package.json index daddc8d77..67971f84a 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "prepublish": "npm run build", "test": "npm run --silent lint && npm run unit-testing && npm run functional-testing", "unit-testing": "nyc --reporter=text-summary --reporter=lcov mocha", + "doc-testing": "docker-compose -f .ci/doc/docker-compose.yml pull; docker-compose -f .ci/doc/docker-compose.yml run doc-tests node index", "functional-testing": "cucumber-js --exit --fail-fast", "lint": "eslint --max-warnings=0 ./src ./test", "build": "node build.js"