{"id":18554280,"url":"https://github.com/oracle/nosql-node-sdk","last_synced_at":"2025-04-09T23:31:07.201Z","repository":{"id":39910712,"uuid":"238534416","full_name":"oracle/nosql-node-sdk","owner":"oracle","description":"Node.js SDK for Oracle NoSQL Database","archived":false,"fork":false,"pushed_at":"2024-10-18T01:23:20.000Z","size":3041,"stargazers_count":10,"open_issues_count":1,"forks_count":6,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-24T13:21:27.265Z","etag":null,"topics":["cloud","database","nodejs","nosql","nosql-database","oracle","oracle-cloud"],"latest_commit_sha":null,"homepage":"https://www.oracle.com/database/nosql/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"upl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oracle.png","metadata":{"files":{"readme":"README-DEV.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-05T19:46:09.000Z","updated_at":"2024-10-18T01:23:24.000Z","dependencies_parsed_at":"2024-08-16T01:55:08.591Z","dependency_job_id":"d2aa26b1-84ca-4455-bba4-378041948f3b","html_url":"https://github.com/oracle/nosql-node-sdk","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fnosql-node-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fnosql-node-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fnosql-node-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fnosql-node-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oracle","download_url":"https://codeload.github.com/oracle/nosql-node-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248129608,"owners_count":21052604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud","database","nodejs","nosql","nosql-database","oracle","oracle-cloud"],"created_at":"2024-11-06T21:21:03.163Z","updated_at":"2025-04-09T23:31:04.777Z","avatar_url":"https://github.com/oracle.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Node.js SDK for Oracle NoSQL Database\n\n## Overview\n\nThis document is for developers of the Node.js SDK for the Oracle NoSQL\nDatabase.  The target audience are those who want to modify\nsource code, run and modify tests and examples and build documentation.\n\n## Getting Started\n\n1. Make sure you have [Node.js](https://nodejs.org) and\n[NPM](https://www.npmjs.com/get-npm) package manager installed on your\nsystem.  The driver requires Node.js version 12.0.0 or later.  It is\nrecommended to install LTS version. NPM package manager is installed\nwith Node.js but could be updated if needed.\n\nTypeScript support is provided for TypeScript versions 5.0.x and higher. \n\n2.  Clone the repository and install development dependencies:\n\n```bash\ngit clone https://github.com/oracle/nosql-node-sdk.git\ncd nosql-node-sdk\nnpm install\n```\n\nAlthough the driver is implemented in JavaScript, with the source code in\n*lib* directory, TypeScript support is provided via .d.ts declaration files\nlocated *src/types* directory.  For JavaScript and TypeScript, the exports\nare declared in *index.js* and *index.d.ts* correspondingly.\n\nDevelopment dependencies are listed in package.json in _devDependencies_\nsection.  The driver does not have runtime external dependencies.\n__npm install__ command above will install all development dependencies\nlocally in node_modules subdirectory.  You may also install some of these\ndependencies globally if needed for convenience.\n\n3. The driver may be used to access\n[Oracle NoSQL Database Cloud Service](https://cloud.oracle.com/nosqldatabase)\nand\n[On-Premise Oracle NoSQL Database](https://docs.oracle.com/en/database/other-databases/nosql-database/index.html).\n\n4.  If developing for the Cloud Service, during development you may use the\ndriver locally by running tests and examples against\n[Oracle NoSQL Database Cloud Simulator](https://docs.oracle.com/en/cloud/paas/nosql-cloud/csnsd/develop-oracle-nosql-cloud-simulator.html)\n\n5. In order to run against Oracle NoSQL Database Cloud Service or against\nOn-Premise Oracle NoSQL Database you need to set up appropriate configuration.\nPlease follow instructions in the __Quickstart__ section of\n[README](./README.md).\n\n## Running Examples\n\nTwo sets of examples are provided, for JavaScript and TypeScript in\n*examples/javascript* and *examples/typescript* directories correspondingly.\n*examples/config* directory contains template JSON configuration files used to\nrun the examples.\n\nFor each set of examples, it is better to copy its contents\ninto a separate directory before running, then follow the *Examples* section\nof [README](./README.md) for futher instructions.\n\nNote that *package.json* files for each set of examples contain the example\ndependencies, which include the SDK itself, and they will be installed from\nNPM registry.  Sometimes you may wish to instead use the SDK directly from\nthe reposity you just cloned instead of NPM version (e.g. when you need to\ntest your changes).  In this case you may use **npm link** command to link to\nthe SDK in your repository before running **npm install**.  E.g.\n\n```bash\ncd typescript_examples_directory\nnpm link path/to/nosql-node-sdk\nnpm install\nnpx tsx table_ops.ts config.json\n```\n\n## Running Tests\n\nUnder test directory, you will see a basic smoke test (*smoke.js*) and unit\ntests located under *unit* subdirectory.  By default, the tests run against\nOracle NoSQL Database Cloud Simulator and assume that the Cloud Simulator\nis running with default endpoint of _localhost:8080_.  In this case you can\nrun the tests without additional parameters:\n\n```bash\nnode smoke.js\n```\n\nIf you want to run the tests against the Oracle NoSQL Database Cloud Service,\nOn-Premise Oracle NoSQL Database or use different configuration for the Cloud\nSimulator, you may provide the configuration file as a parameter:\n\n```bash\nnode smoke.js config.json\n```\n\nThe configuration file is usually JSON (but may also be JavaScript module)\nthat contains configuration object used to create _NoSQLClient_ instance, as\ndescribed in the API documentation for _NoSQLClient_.\n\n### Running Unit Tests\n\n__Note:__\n\n__It is recommended to run the unit tests only against the Cloud Simulator or\non-premise NoSQL Database and not against the Cloud Service as the latter\nwill consume cloud resources and may incur significant cost.__\n\nThe unit tests are run with [Mocha](https://mochajs.org/) and also use some\nadditional libraries, such as chai, chai-as-promised, etc.  These are installed\nlocally as development dependencies (see *Getting Started*).\n\nTo run all unit tests with Cloud Simulator and default NoSQLClient\nconfiguration (Cloud Simulator with endpoint localhost:8080), go to the root\ndirectory of the repository and do:\n\n```bash\nnpm test\n```\n\n#### Using Custom NoSQLClient Configuration\n\nTo run unit tests with different NoSQLClient configuration, such as for\nOn-Premise Oracle NoSQL Database or Cloud Simulator with custom endpoint, you\ncan provide the configuration file name or path as a parameter with\n*--nosql-config* option:\n\n```bash\nnpm test -- --nosql-config /path/to/config.json\n```\n\nYou may also invoke mocha directly:\n\n```bash\nnode_modules/.bin/mocha --nosql-config /path/to/config.json\n```\n\n#### Mocha Options\n\nMocha command is available in node_modules/.bin directory after development\ndependencies are installed locally, or if you installed mocha globally, mocha\ncommand will be available to use without specifying its path.\n\nThe options used to run the tests and the list of test files are configured in\n__.mocharc.json__ Mocha configuration file in the repository root directory.\nNote that .mocharc.json sets _min_ test reporter, so you will not\nsee the output for each individual successful testcase, only errors are\nreported.\n\n#### Running Individual Test Cases\n\nIf you wish not to use options and test files specified in *.mocharc.json*,\npass _--no-config_ option to mocha.\n\nThis can be used to run individual testcases instead of the whole suite:\n\n```bash\ncd test/unit\n../../node_modules/.bin/mocha --no-config table_ddl.js\n../../node_modules/.bin/mocha --no-config get.js --nosql-config config.json\n.....\n```\n\n#### Running Query Test\n\nNote that running the full query test may take a long time because of many\ntestcases for advanced query functionality.  You may choose to run only basic\nquery testcases by using _--basic-query-only_ option with value _true_.  This\noption may be used when running only the query test or when running the whole\ntest suite and can also be combined with other options:\n\n```bash\nnpm test -- --basic-query-only true\n```\n\n```bash\ncd test/unit\n../../node_modules/.bin/mocha --no-config query.js --basic-query-only true\n```\n\n#### Running Against Specific KVStore Version\n\nYou can specify kvstore version of the NoSQL service against which you run\nunit tests by using _--kv_ option.  This can be done when running the whole\ntest suite or individual tests:\n\n```bash\nnpm test -- --kv 20.1\n```\n\n```bash\ncd test/unit\n../../node_modules/.bin/mocha --no-config query.js --kv 20.1\n```\n\nThis option allows you to run unit tests against older releases and thus skip\ntesting latest features not supported in these releases.\n\n### Unit Tests for TypeScript Declarations\n\nUnit tests for TypeScript declarations for the driver are located in\n*test/unit/types* directory.  These are compile-time only tests and check the\ncorrectness of API signatures and accompanying interfaces and types, as well\nas make sure TypeScript compiler flags errors when the APIs are used\nincorrectly.  As such, these test files only need to be compiled (you can\nalso see any errors flagged in VSCode).\n\nThese tests use [expect-type](https://www.npmjs.com/package/expect-type)\npackage as well as *@ts-expect-error* directive to detect incorrect use of the\nAPIs.\n\nUsing **npm test** command as above will also invoke these tests.\nAlternatively, you can invoke (compile) them separately:\n\n```bash\ncd test/unit/types\nnpx tsc\n```\n\n## Linting and Debugging\n\n### Linting\n\n[ESLint](https://eslint.org/) and\n[eslint-plugin-require-path-exists](https://github.com/BohdanTkachenko/eslint-plugin-require-path-exists) plugin are installed as part\nof development dependencies.  __.eslintrc.js__ configuration file is also present\nin the repository root directory.\n\nYou may lint directories or files by just running eslint from the repository\nroot directory:\n\n```bash\nnode_modules/.bin/eslint lib\nnode_modules/.bin/eslint test\n```\n\n(If you installed eslint globally you can use eslint command without\nspecifying its path)\n\nIf you are using [Visual Studio Code](https://code.visualstudio.com/) as your\nIDE, you may install _VS Code ESLint extension_ from the marketplace.  This\nwill show any problems found by ESLint directly in the source code editor.\n\n### Debugging\n\nThe following applies if you are using\n[Visual Studio Code](https://code.visualstudio.com/):\n\n#### JavaScript\n\nOnce you open the repository root directory in VSCode, you can add and edit\nlaunch configurations that will be stored in .vscode/launch.json file.\n\nTo debug standalone example or test, just use default configuration of type\n\"node\", for example:\n\n```json\n    {\n        \"type\": \"node\",\n        \"request\": \"launch\",\n        \"name\": \"basic_example\",\n        \"program\": \"${workspaceFolder}/examples/basic_example.js\",\n        \"args\": [ \"/path/to/config.json\" ]\n    }\n```\n\nYou may also debug Mocha unit tests in VSCode.  [This page](https://github.com/microsoft/vscode-recipes/tree/master/debugging-mocha-tests) has more information.\n\nFor example, you can use the following launch configuration to debug\nindividual unit test:\n\n```json\n    {\n        \"type\": \"node\",\n        \"request\": \"launch\",\n        \"name\": \"put_test\",\n        \"program\": \"${workspaceFolder}/node_modules/mocha/bin/_mocha\",\n        \"args\": [ \"--no-config\", \"${workspaceFolder}/test/unit/put.js\" ],\n        \"console\": \"integratedTerminal\",\n        \"internalConsoleOptions\": \"neverOpen\"\n    }\n```\n\n#### TypeScript\n\nTo debug your Node.js TypeScript application that uses the SDK, please follow\n[this guide](https://code.visualstudio.com/docs/typescript/typescript-debugging).\n\nNote that *tsconfig.json* for your application must include either *sourceMap*\nor *inlineSourceMap* set to *true* in *compilerOptions*.\n\nHere is the example launch configuration to run one of the TypeScript examples\nthat come with the SDK:\n\n```json\n    {\n        \"type\": \"node\",\n        \"request\": \"launch\",\n        \"name\": \"debug_query_ops_example\",\n        \"program\": \"${workspaceFolder}/query_ops.ts\",\n        \"args\": [ \"config_cloud.json\" ],\n        \"preLaunchTask\": \"npm: build\",\n        \"outFiles\": [ \"${workspaceFolder}/dist/*.js\" ]\n    }\n```\n\nThis will allow you to debug your application code and also go into JavaScript\ncode of the SDK.\n\nThe *preLaunchTask* property enables building the application before running,\nwith compiled JavaScript code going into *dist* directory (see *outFiles*\nproperty).\n\n## Building Documentation\n\nAPI documentation is built with [TypeDoc](https://typedoc.org/) using:\n\n* Documentation comments in the TypeScript declaration files in *src/types*\ndirectory.\n* Tutorials in *doc/guides* directory.\n\nTo build API documentation, in the repository root directory do:\n\n```bash\nnpm run docs\n```\n\nor use typedoc directly:\n\n```\nnpx typedoc\n```\n\nThe resulting API documentation is generated in *doc/site* directory. You can\nstart browsing from __doc/site/index.html__ file.\n\nThe build is controled by *typedoc.json* configuration file. For more\ninformation see [TypeDoc Options](https://typedoc.org/options/).\n\n### Publishing Documentation\n\nThe generated documentation is published on\n[GitHub](https://oracle.github.io/nosql-node-sdk/). Publication is automatic\nbased on changes pushed to the gh-pages branch of the\n[Oracle NoSQL Database Node.js SDK](https://github.com/oracle/nosql-node-sdk)\nrepository.\n\nTo publish:\n\nIn these instructions \u003cnosql-node-sdk\u003e is the path to a current clone from\nwhich to publish the documentation and \u003cnosql-node-doc\u003e is the path to\na fresh clone of the gh-pages branch (see instructions below).\n\n1. clone the gh-pages branch of the SDK repository into \u003cnosql-node-doc\u003e:\n\n        git clone --single-branch --branch gh-pages https://github.com/oracle/nosql-node-sdk.git nosql-node-doc\n\n2. generate documentation in the master (or other designated) branch of the\nrepository:\n\n        $ cd \u003cnosql-node-sdk\u003e\n        $ rm -rf doc/site\n        $ npm run docs\n\n3. copy generated doc to the gh-pages repo\n\n        $ cp -r \u003cnosql-node-sdk\u003e/doc/site/* \u003cnosql-node-doc\u003e\n\n4. commit and push after double-checking the diff in the nosql-node-doc\nrepository\n\n        $ cd \u003cnosql-node-doc\u003e\n        $ git commit\n        $ git push\n\nThe new documentation will automatically be published.\n\n## Packaging and Release\n\nThe release package includes\n\n* the library runtime\n* typescript declaration files\n* examples\n\n### Intallable Archive\n\nTo build a local tarball that can be installed using npm:\n\n```\nnpm pack\n```\nThis creates oracle-nosqldb-x.y.z.tgz which can be installed by using:\n\n```\nnpm install oracle-nosqldb-x.y.z.tgz\n```\n\n### Smoke Test for Validity\n\nSee *smoke.js* in section **Running Tests**.\n\n### Upload to npmjs.com\n\nTBD\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fnosql-node-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foracle%2Fnosql-node-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fnosql-node-sdk/lists"}