From dd16e909026e556ba2157667b692f7d3c8a567ca Mon Sep 17 00:00:00 2001 From: Geoff Doty Date: Mon, 2 Apr 2018 07:21:19 -0400 Subject: [PATCH] updated docs --- CONTRIBUTING.md | 72 ++++++++++++++ LICENSE | 21 ++++ README.md | 15 ++- docs/{doc.md => api.md} | 206 ++++++++++++++++++++-------------------- 4 files changed, 208 insertions(+), 106 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE rename docs/{doc.md => api.md} (94%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ac0e83a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing + +So you want to contribute, nice. **Thank you**. + +Bug reports and code and documentation patches are all welcome. You can help this project also by using the development version and by reporting any bugs you might encounter. + +You may contribute in several ways like: + +* Creating new features +* Fixing bugs +* Improving documentation and examples +* Translating any document here to your language + +## Table of contents + +* [Contributing](#contributing) + * [Developing](#developing) + * [Running tests](#running-tests) + * [Reporting a bug](#reporting-a-bug) + * [Request a feature](#request-a-feature) + * [Commit message](#commit-message) + * [Code style](#code-style) + +## Developing + +There is only one main source file in the project. It is the [/src/index.js](/src/index.js). +The [test/index.spec.js](test/index.spec.js) is for now the only unit test file in the project. + +The `dist` includes the minified version of the source code. + +## Running tests + +Run unit tests using this command: + +```bash +npm test +``` + +## Reporting a bug + +Use the [GitHub issue tracker](https://github.com/n2geoff/js-lib/issues) to report any bug you find. +Bugs description should include: + +* How to reproduce the bug; +* Easy to understand title; + +Would be nice to have some code showing how to reproduce the code, you may use [gist](https://gist.github.com) or [Codepen](https://codepen.io) for uploading your example code. + +## Request a feature + +Use the [GitHub issue tracker](https://github.com/n2geoff/js-lib/issues) to request a new feature. + +Keep in mind, this is a pure javascript library + +Feel free to port it to your favorite framework, such as [RiotJS](http://riotjs.com), Angular or VueJs in a new repository. + +## Commit message + +Commit messages should includes GitHub number reference and a imperative easy to understand sentence. + +## Coding style + +If it is supported in all major browers without transpiling, then please use those JavaScript language features in your code, with one caveat -- readablity is king. + +Currently all ES5 and ES6/ES2015 are available. + +This project is linted agaist [JSHint](https://github.com/jshint/jshint) and the [`.jshintrc`](.jshintrc) is dead-simple, and all you need to followed. + +Thank you for reading this. + + +Hey, **star** this *repo* and/or share it with your friends. \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e671a85 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License + +Copyright (c) 2018 Geoff Doty + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index 2f580c0..6d6b876 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,20 @@ Not done yet! ## Docs -- [docs](docs/doc.md) +- [docs](docs/api.md) ## Tests npm test -## TODO -- implement local storage \ No newline at end of file +## Support + +Please open [an issue](https://github.com/n2geoff/record.js/issues/new) for support. + +## Contributing + +Anyone is welcome to contribute, however, if you decide to get involved, please take a moment to review the [guidelines](CONTRIBUTING.md), there minimalistic;) + +## License + +[MIT](LICENSE) diff --git a/docs/doc.md b/docs/api.md similarity index 94% rename from docs/doc.md rename to docs/api.md index a2c3f91..eddc85c 100644 --- a/docs/doc.md +++ b/docs/api.md @@ -1,103 +1,103 @@ -# Record.JS - -- [constructor][1] -- [add][2] -- [find][3] -- [remove][4] -- [count][5] - -## constructor - -**Parameters** - -- `init` **[array][6]** collection to start with -- `opts` **[object][7]** - - `opts.store` **[object][7]** localStorage ID to use - - `opts.debug` **[object][7]** show console logs - -**Examples** - -```javascript -// create a new record (in-memory) -let pets = new Record(); -``` - -## add - -Add record to collection creating an sudo unique id if -one not provided - -**Parameters** - -- `entry` **[Object][7]** object(s) you want to store - -**Examples** - -```javascript -// add pet to collection -let dog = pets.add({"name": "Yonkers", "age": 5}); - -// [{"id": "14rj345k9", "name": "Yonkers", "age": 5}] -``` - -Returns **[array][6]** record added - -## find - -Finds records in collection by id or object filter. - -**Parameters** - -- `key` **([string][8] \| [number][9])** (optional) by id, or object - -**Examples** - -```javascript -// find all -let all = collection.find(); -``` - -```javascript -// find by id -let record = collection.find(1); -``` - -```javascript -// filter by object -let dogs = collection.find({"type": "dog"}); -``` - -Returns **[array][6]** matching records - -## remove - -- **See: [find][10]** - -Remove record(s) from collection. Leverages same functionality as `find` - -**Parameters** - -- `entry` **any** (optional) - -**Examples** - -```javascript -// remove all records by type -let removed = collection.remove({"type": "cat"}); -``` - -Returns **[array][6]** records removed - -## count - -Returns **[number][9]** count of records in collection - -[1]: #constructor - -[2]: #add - -[3]: #find - -[4]: #remove - -[5]: #count +# Record.JS + +- [constructor][1] +- [add][2] +- [find][3] +- [remove][4] +- [count][5] + +## constructor + +**Parameters** + +- `init` **[array][6]** collection to start with +- `opts` **[object][7]** + - `opts.store` **[object][7]** localStorage ID to use + - `opts.debug` **[object][7]** show console logs + +**Examples** + +```javascript +// create a new record (in-memory) +let pets = new Record(); +``` + +## add + +Add record to collection creating an sudo unique id if +one not provided + +**Parameters** + +- `entry` **[Object][7]** object(s) you want to store + +**Examples** + +```javascript +// add pet to collection +let dog = pets.add({"name": "Yonkers", "age": 5}); + +// [{"id": "14rj345k9", "name": "Yonkers", "age": 5}] +``` + +Returns **[array][6]** record added + +## find + +Finds records in collection by id or object filter. + +**Parameters** + +- `key` **([string][8] \| [number][9])** (optional) by id, or object + +**Examples** + +```javascript +// find all +let all = collection.find(); +``` + +```javascript +// find by id +let record = collection.find(1); +``` + +```javascript +// filter by object +let dogs = collection.find({"type": "dog"}); +``` + +Returns **[array][6]** matching records + +## remove + +- **See: [find][10]** + +Remove record(s) from collection. Leverages same functionality as `find` + +**Parameters** + +- `entry` **any** (optional) + +**Examples** + +```javascript +// remove all records by type +let removed = collection.remove({"type": "cat"}); +``` + +Returns **[array][6]** records removed + +## count + +Returns **[number][9]** count of records in collection + +[1]: #constructor + +[2]: #add + +[3]: #find + +[4]: #remove + +[5]: #count