{"id":21352065,"url":"https://github.com/static-dev/spike-records","last_synced_at":"2025-07-12T20:32:03.145Z","repository":{"id":57367481,"uuid":"55182338","full_name":"static-dev/spike-records","owner":"static-dev","description":":dvd: Spike plugin to load async locals into your views","archived":false,"fork":false,"pushed_at":"2019-02-05T12:31:18.000Z","size":672,"stargazers_count":20,"open_issues_count":7,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-08-11T08:52:06.610Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/static-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-31T20:54:45.000Z","updated_at":"2020-04-15T12:27:32.000Z","dependencies_parsed_at":"2022-08-23T19:30:30.859Z","dependency_job_id":null,"html_url":"https://github.com/static-dev/spike-records","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/static-dev%2Fspike-records","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/static-dev%2Fspike-records/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/static-dev%2Fspike-records/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/static-dev%2Fspike-records/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/static-dev","download_url":"https://codeload.github.com/static-dev/spike-records/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225834367,"owners_count":17531471,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T03:12:26.856Z","updated_at":"2024-11-22T03:12:27.542Z","avatar_url":"https://github.com/static-dev.png","language":"JavaScript","readme":"# Spike Records\n\n[![npm](http://img.shields.io/npm/v/spike-records.svg?style=flat)](https://badge.fury.io/js/spike-records) [![tests](http://img.shields.io/travis/static-dev/spike-records/master.svg?style=flat)](https://travis-ci.org/static-dev/spike-records) [![dependencies](http://img.shields.io/david/static-dev/spike-records.svg?style=flat)](https://david-dm.org/static-dev/spike-records) [![coverage](http://img.shields.io/coveralls/static-dev/spike-records.svg?style=flat)](https://coveralls.io/github/static-dev/spike-records?branch=master)\n\nremote data -\u003e static templates\n\n## Why should you care?\n\nStatic is the best, but sometimes you need to fetch data from a remote source which makes things not so static. Spike Records is a little webpack plugin intended for use with [spike](https://github.com/static-dev/spike) which allows you to make data pulled from a file or url available in your view templates.\n\nIt can pull data from the following places:\n\n- A javascript object\n- A file containing a javascript object or JSON\n- A URL that returns JSON\n- A [GraphQL](http://graphql.org) endpoint\n\n## Installation\n\nInstall into your project with `npm i spike-records -S`.\n\nThen load it up as a plugin in `app.js` like this:\n\n```javascript\nconst Records = require('spike-records')\nconst standard = require('reshape-standard')\nconst locals = {}\n\nmodule.exports = {\n  reshape: standard({ locals: () =\u003e locals }),\n  plugins: [new Records({\n    addDataTo: locals,\n    test: { file: 'data.json' }\n  })]\n}\n```\n\n## Usage\n\nThe primary use case for spike-records is to inject local variables into your html templates, although technically it can be used for anything. In the example above, we use the [reshape-standard](https://github.com/reshape/standard) plugin pack to add variables (among other functionality) to your html. Spike's default template also uses `reshape-standard`.\n\nIn order to use the results from spike-records, you must pass it an object, which it will put the resolved data on, using the `addDataTo` key. This plugin runs early in spike's compile process, so by the time templates are being compiled, the object will have all the data necessary on it. If you are using the data with other plugins, ensure that spike-records is the first plugin in the array.\n\nI know this is an unusual pattern for a javascript library, but the way it works is quite effective in this particular system, and affords a lot of flexibility and power.\n\nThe records plugin accepts an object, and each key in the object (other than `addDataTo`) should contain another object as it's value, with either a `file`, `url`, `data`, `graphql` or `callback` property. For example:\n\n```js\nconst Records = require('spike-records')\nconst locals = {}\nfunction myFunc () {\n  // call any arbitrary API or computation to produce data\n  return new Promise((resolve, reject) =\u003e {...})\n}\n\nmodule.exports = {\n  plugins: [new Records({\n    addDataTo: locals,\n    one: { file: 'data.json' },\n    two: { url: 'http://api.carrotcreative.com/staff' },\n    three: { data: { foo: 'bar' } },\n    four: {\n      graphql: {\n        url: 'http://localhost:1234',\n        query: 'query { allPosts { title } }',\n        variables: 'xxx', // optional\n        headers: { authorization: 'Bearer xxx' } // optional\n      }\n    },\n    five: { callback: myFunc }\n  })]\n}\n```\n\nWhatever data source you provide, it will be resolved and added to your view templates as `[key]`. So for example, if you were trying to access `three` in your templates, you could access it with `three.foo`, and it would return `'bar'`, as such:\n\n```jade\np {{ three.foo }}\n```\n\nNow let's get into some more details for each of the data types.\n\n### File\n\n`file` accepts a file path, either absolute or relative to your [spike](https://github.com/static-dev/spike) project's root. So for the example above, it would resolve to `/path/to/project/data.json`.\n\n### Url\n\n`url` accepts either a string or an object. If provided with a string, it will make a request to the provided url and parse the result as JSON, then return it as a local. If you need to modify this behavior, you can pass in an object instead. The object is passed through directly to [rest.js](https://github.com/cujojs/rest), their docs for acceptable values for this object [can be found here](https://github.com/cujojs/rest/blob/master/docs/interfaces.md#common-request-properties). These options allow modification of the method, headers, params, request entity, etc. and should cover any additional needs.\n\n### Data\n\nThe most straightforward of the options, this will just pass the data right through to the locals. Also if you provide a A+ compliant promise for a value, it will be resolved and passed in to the template.\n\n## Additional Options\n\nAlongside any of the data sources above, there are a few additional options you can provide in order to further manipulate the output.\n\n### Transform\n\nIf you want to transform the data from your source in any way before injecting it as a local, you can use this option. For example:\n\n```js\nconst Records = require('spike-records')\nconst locals = {}\n\nmodule.exports = {\n  plugins: [new Records({\n    addDataTo: locals,\n    blog: {\n      url: 'http://blog.com/api/posts',\n      transform: (data) =\u003e { return data.response.posts }\n    }\n  })]\n}\n```\n\n### Transform Raw\n\nIf you want to transform the data from your source before it is processed by rest, for instance to remove cross site scripting protections, you can use this option. For example:\n\n```js\nconst Records = require('spike-records')\nconst locals = {}\n\nmodule.exports = {\n  plugins: [new Records({\n    addDataTo: locals,\n    blog: {\n      transformRaw: (data) =\u003e { return data.replace('])}while(1);\u003c/x\u003e', '') },\n      url: 'https://medium.com/glassboard-blog/?format=json'\n    }\n  })]\n}\n```\n\n### Template\n\nUsing the template option allows you to write objects returned from records to single page templates. For example, if you are trying to render a blog as static, you might want each `post` returned from the API to be rendered as a single page by itself.\n\nThe `template` option is an object with `path` and `output` keys. `path` is an absolute or relative path to a template to be used to render each item, and `output` is a function with the currently iterated item as a parameter, which should return a string representing a path relative to the project root where the single view should be rendered. For example:\n\n```js\nconst Records = require('spike-records')\nconst locals = {}\n\nmodule.exports = {\n  plugins: [new Records({\n    addDataTo: locals,\n    blog: {\n      url: 'http://blog.com/api/posts',\n      template: {\n        path: 'templates/single.sgr',\n        output: (post) =\u003e { return `posts/${post.slug}.html` }\n      }\n    }\n  })]\n}\n```\n\nNote that for this feature to work correctly, the data returned from your data source must be an array. If it's not, the plugin will throw an error. If you need to transform the data before it is rendered into templates, you can do so using a `transform` function, as such:\n\n```js\nconst Records = require('spike-records')\nconst locals = {}\n\nmodule.exports = {\n  plugins: [new Records({\n    addDataTo: locals,\n    blog: {\n      url: 'http://blog.com/api/posts',\n      template: {\n        transform: (data) =\u003e { return data.response.posts },\n        path: 'templates/single.sml',\n        output: (post) =\u003e { return `posts/${post.slug}.html` }\n      }\n    }\n  })]\n}\n```\n\nIf you use a `transform` function outside of the `template` block, this will still work. The difference is that a `transform` inside the `template` block will only use the transformed data for rendering single templates, whereas the normal `transform` option will alter that data that is injected into your view templates as locals, as well as the single templates.\n\nInside your template, a local called `item` will be injected, which contains the contents of the item for which the template has been rendered. It will also contain all the other locals injected by spike-records and otherwise, fully transformed by any `transform` functions provided.\n\n## License \u0026 Contributing\n\n- Details on the license [can be found here](LICENSE.md)\n- Details on running tests and contributing [can be found here](contributing.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatic-dev%2Fspike-records","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatic-dev%2Fspike-records","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatic-dev%2Fspike-records/lists"}