{"id":19163253,"url":"https://github.com/oada/oada-cache","last_synced_at":"2025-05-07T11:21:51.116Z","repository":{"id":33152138,"uuid":"140020020","full_name":"OADA/oada-cache","owner":"OADA","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-26T09:49:02.000Z","size":486,"stargazers_count":2,"open_issues_count":32,"forks_count":0,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-19T21:25:48.425Z","etag":null,"topics":["oada"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OADA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-07-06T18:52:15.000Z","updated_at":"2021-01-28T02:34:42.000Z","dependencies_parsed_at":"2025-03-12T11:21:24.519Z","dependency_job_id":"624a98aa-62c7-45fa-a034-42b7275a052d","html_url":"https://github.com/OADA/oada-cache","commit_stats":{"total_commits":125,"total_committers":7,"mean_commits":"17.857142857142858","dds":"0.43200000000000005","last_synced_commit":"9f188e78e19ca291a3e8a4e242c1efb102c74d16"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Foada-cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Foada-cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Foada-cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Foada-cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OADA","download_url":"https://codeload.github.com/OADA/oada-cache/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252866123,"owners_count":21816397,"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":["oada"],"created_at":"2024-11-09T09:14:39.514Z","updated_at":"2025-05-07T11:21:51.094Z","avatar_url":"https://github.com/OADA.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# oada-cache\n\nA client tool for interacting with an [OADA server](https://www.github.com/OADA/oada-srvc-docker/) instance. It can be used for fully cached web applications, data import scripts, IoT devices streaming data, and back-end microservices.\n\n## Installation\n`npm install @oada/oada-cache`\n\n`var oada = require(\"@oada/oada-cache\")`\n\n\n#### connect\n```javascript\nvar connection = await oada.connect({\n  domain: \"https://api.oada.com\",\n  options: {\n    redirect: \"http://localhost:8000/oauth2/redirect.html\",\n    metadata: \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n    scope: \"oada.yield:all\"\n  }\n})\n```\nThis will initiate OADA OAUTH-style authentication.\n\n#### get\n```javascript\nvar response = await connection.get({path: '/bookmarks/test'})\n```\n\n#### put\n```javascript\nvar response = await connection.put({\n  path: \"/bookmarks/test\",\n  data: { \"power_level\": 9001},\n  headers: {\"Content-Type\": \"application/json\"}\n})\n\n```\n#### post\n```javascript\nvar response = await connection.post({\n  path: \"/bookmarks/test\",\n  data: { \"power_level\": 9001},\n  headers: {\"Content-Type\": \"application/json\"}\n})\nvar  = response.headers[\"content-location\"]; // A path including the uuid created\n\n```\n#### delete\n```javascript\nvar response = await connection.delete({\n  path: \"/bookmarks/test\",\n  headers: {\"Content-Type\": \"application/json\"}\n})\n```\n\n## \"Advanced\" API\n#### tree\nA `tree` option can be used in many of the `oada-cache` API calls as a means to specify the data structure you intend to create or pull from the OADA server. It is used to represent a particular subgraph on the sever. The use of a `_type` key in the tree indicates that a resource break exists at this particular level of the tree and a link should be used to connect the parent resource to the resource(s) at this location. A `_rev` key in the tree indicates that _versioned_ links should be created at this location; versioned links indicate that the parent will be updated with new revision numbers (`_rev`) each time the linked child resource is altered. A `*` key in the tree represents a placeholder when a particular key cannot be specified.\n\n```javascript\nvar todoTree = {\n  \"bookmarks\": { //Represents a user's \"home\" directory\n    \"_type\": \"application/vnd.oada.bookmarks.1+json\",\n    \"_rev\": 0,\n    \"todoList\": {\n      \"_type\": \"application/vnd.oada.todoList.1+json\",\n      \"_rev\": 0,\n      \"todo-index\": {\n        \"*\": {\n          \"_type\": \"application/vnd.oada.todoItem.1+json\",\n      \t  \"_rev\": 0,\n        }\n      }\n    }\n  }\n};\n```\n\n\n#### get\nUsing the `tree` option for recursive retrieval of en entire OADA subgraph:\n```javascript\nvar response = await connection.get({\n  path: \"/bookmarks/todoList\",\n  tree: todoTree\n})\n```\nGETs that include this tree option will recursively retreive and merge the data into the object returned. In this example, the `tree` option tells it to recursively GET all of the data below the object at the given path. The `*` key matches all keys in the `todo-index` object; since each of these are a link to a resource, GETs will be performed to retreive each of these resources.\n\n\n#### put\nUsing the `tree` option to execute a \"smart PUT\", ensuring that all parent resources will be created on the server.\n```javascript\nvar response = await connection.put({\n  path: \"/bookmarks/todoList/todo-index/fj029j52-mc20m23c23\",\n  data: {\"order\": 1, text: \"get groceries\"},\n  headers: {\"Content-Type\": \"application/vnd.oada.todoItem\"},\n  tree: todoTree\n})\n```\nA PUT of this variety may actually result in several PUTs. For example, when `/bookmarks` is an empty object, the above PUT request will resources for the objects at `/bookmarks/todoList` and `/bookmarks/todoList/todo-index/fj029j52-mc20m23c23`.\n\n#### post\nPOSTs including the `tree` option are identical to PUT requests except a uuid is appended to the given request `path`.\n\n#### delete\nUsing the `tree` option on a DELETE request will recursively DELETE all resources and links below the request `path`.\n```javascript\nvar response = await connection.delete({\n  path: \"/bookmarks/todoList\",\n  headers: {\"Content-Type\": \"application/vnd.oada.todoList.1+json\"},\n  tree: todoTree\n})\n```\n\n## Watch\nResource watching provides a change feed of updates on demand from the resource rooted at the given `path`. Watches are implemented as an extension of a GET request when the 'watch' key is supplied. When a watch is established, it will automatically keep the cache synced with the incoming change feed. When a watch is initiated, the current `_rev` of the resources is automatically passed along, and any remote changes will be pushed down to bring that resource up to date. The optional `callback` key of the `watch` object is used to supply a callback function as changes are received; this callback receives a `payload` argument containing the change. The `payload` key of the `watch` object is used to supply additional data to the callback payload.\n```javascript\nconst watchHandler = function(payload) {\n  console.log(payload); // {foo: 'bar', response: {...}, request: {...}}\n  console.log(payload.response.change.type); // Either 'merge' or 'delete' given the particular change that occurred.\n  console.log(payload.response.change.body); //JSON object rooted at the watch path '/bookmarks/todoList'; For deletes, this sparse tree terminates at a key with the value `null` to indicate the deleted key.\n}\n\nvar response = await connection.get({\n  path: \"/bookmarks/todoList\",\n  watch: {\n    payload: { foo: 'bar' }\n    callback: watchHandler\n  }\n});\n```\n\n\n\n\n### Developing against an application\nTo further develop this library against e.g., a runnning application, utilize the `npm run build-watch` command to continuously build the source code. Utilize the `npm run dev` command to watch for changes to the built code and copy it into another project directory (e.g., node_modules of an application being developed); you must first set the `APP_DIR` environment variable to the root path of a directory containing a node_modules directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foada%2Foada-cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foada%2Foada-cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foada%2Foada-cache/lists"}