Skip to content

Commit

Permalink
Improvments to readme generation
Browse files Browse the repository at this point in the history
  • Loading branch information
zakkudo committed Sep 6, 2018
1 parent f0a7c73 commit f5797ce
Show file tree
Hide file tree
Showing 13 changed files with 193 additions and 161 deletions.
79 changes: 35 additions & 44 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,12 @@
<a name="module_@zakkudo/query-string"></a>

# @zakkudo/query-string
<p>

Make working with url query-strings enjoyable.
</p>

<p>
<a href="https://travis-ci.org/zakkudo/query-string">
<img src="https://travis-ci.org/zakkudo/query-string.svg?branch=master"
alt="Build Status" /></a>
<a href="https://coveralls.io/github/zakkudo/query-string?branch=master">
<img src="https://coveralls.io/repos/github/zakkudo/query-string/badge.svg?branch=master"
alt="Coverage Status" /></a>
<a href="https://snyk.io/test/github/zakkudo/query-string">
<img src="https://snyk.io/test/github/zakkudo/query-string/badge.svg"
alt="Known Vulnerabilities"
data-canonical-src="https://snyk.io/test/github/zakkudo/query-string"
style="max-width:100%;" /></a>
</p>

<h3>Why use this?</h3>

[![Build Status](https://travis-ci.org/zakkudo/query-string.svg?branch=master)](https://travis-ci.org/zakkudo/query-string)
[![Coverage Status](https://coveralls.io/repos/github/zakkudo/query-string/badge.svg?branch=master)](https://coveralls.io/github/zakkudo/query-string?branch=master)
[![Known Vulnerabilities](https://snyk.io/test/github/zakkudo/query-string/badge.svg)](https://snyk.io/test/github/zakkudo/query-string)

## Why use this?

- Consistancy with simplicity
- The instance acts like a plain-old-object
Expand All @@ -28,7 +15,7 @@ Make working with url query-strings enjoyable.
Update the properties after initialization and the serialization will reflect the updates
- Complex params are automatically serialized and deserialized from json

<h3>Install</h3>
## Install

```console
# Install using npm
Expand All @@ -40,8 +27,10 @@ npm install @zakkudo/query-string
yarn add @zakkudo/query-string
```

**Example** *(Initializing with an object)*
```js
## Examples

### Initializing with an object
```javascript
import QueryString from '@zakkudo/query-string';

const query = new QueryString({
Expand All @@ -54,9 +43,12 @@ String(query) // '?page=3&title=awesomeness&complex=%7B%22test%22%3A%22value%22%
query.toString() // '?page=3&title=awesomeness&complex=%7B%22test%22%3A%22value%22%7D&'

const url = `http://example${query}` //Automatically serializes correctly

const url = `http://example${query}` //Automatically serializes correctly with changes
```
**Example** *(Initializing with a URL)*
```js

### Initializing with a URL and making changes dynamically
```javascript
import QueryString from '@zakkudo/query-string';

const query = new QueryString('http://example?page=3&title=awesomeness');
Expand All @@ -66,8 +58,9 @@ delete query.page;
String(query) // '?title=awesomeness'
query.toString() // '?title=awesomeness'
```
**Example** *(Parsing an invalid query string with duplicate &#x27;?&#x27;)*
```js

### Error handling
```javascript
import QueryString from '@zakkudo/query-string';
import QueryStringError from '@zakkudo/query-string/QueryStringError';

Expand All @@ -82,14 +75,17 @@ try {
}
```

<a name="module_@zakkudo/query-string..QueryString"></a>
## API

<a name="module_@zakkudo/query-string"></a>

## @zakkudo/query-string~QueryString ⏏
**Kind**: Exported class [<code>@zakkudo/query-string</code>](#module_@zakkudo/query-string)
<a name="module_@zakkudo/query-string..QueryString"></a>

### @zakkudo/query-string~QueryString ⏏
**Kind**: Exported class
<a name="new_module_@zakkudo/query-string..QueryString_new"></a>

### new QueryString(data)
#### new QueryString(data)
**Throws**:

- [<code>QueryStringError</code>](#module_@zakkudo/query-string/QueryStringError..QueryStringError) On issues parsing or serializing the configuration
Expand All @@ -98,29 +94,24 @@ try {
| --- | --- | --- |
| data | <code>String</code> \| <code>Object</code> \| <code>QueryString</code> | Initial data. A url `String` will be parsed, and `Object`/`QueryString` instances will be copied. |

<a name="module_@zakkudo/query-string..QueryString+toString"></a>

### queryString.toString() ⇒ <code>String</code>
Converts the object into its serialized query string representation
that can be used in a url.

**Kind**: instance method of [<code>QueryString</code>](#module_@zakkudo/query-string..QueryString)
**Returns**: <code>String</code> - The serialized representation of the `QueryString`. It
will be an empty string if there are no params to serialize.
<a name="module_@zakkudo/query-string/QueryStringError"></a>

<a name="module_@zakkudo/query-string/QueryStringError..QueryStringError"></a>

## @zakkudo/query-string/QueryStringError~QueryStringError ⇐ <code>Error</code> ⏏
### @zakkudo/query-string/QueryStringError~QueryStringError ⇐ <code>Error</code> ⏏
Error class used by QueryString for raising errors
generated during parsing or serialization.

**Kind**: Exported class [<code>@zakkudo/query-string/QueryStringError</code>](#module_@zakkudo/query-string/QueryStringError)
**Kind**: Exported class
**Extends**: <code>Error</code>

* [~QueryStringError](#module_@zakkudo/query-string/QueryStringError..QueryStringError) ⇐ <code>Error</code>
* [new QueryStringError(message, url)](#new_module_@zakkudo/query-string/QueryStringError..QueryStringError_new)
* [.url](#module_@zakkudo/query-string/QueryStringError..QueryStringError+url)

<a name="new_module_@zakkudo/query-string/QueryStringError..QueryStringError_new"></a>

### new QueryStringError(message, url)
#### new QueryStringError(message, url)

| Param | Type | Description |
| --- | --- | --- |
Expand All @@ -129,7 +120,7 @@ generated during parsing or serialization.

<a name="module_@zakkudo/query-string/QueryStringError..QueryStringError+url"></a>

### queryStringError.url
#### queryStringError.url
The related url fragment when the error was generated

**Kind**: instance property of [<code>QueryStringError</code>](#module_@zakkudo/query-string/QueryStringError..QueryStringError)
3 changes: 2 additions & 1 deletion jsdoc.config.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
"opts": {
"destination": "./documentation",
"recurse": true,
"encoding": "utf8"
"encoding": "utf8",
"readme": "src/README.md"
}
}
18 changes: 16 additions & 2 deletions scripts/build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,19 @@

set -e

./node_modules/.bin/babel src --out-dir build --source-maps inline --ignore "src/test.js" --ignore "src/*.test.js"
cp package.json build/package.json
PROJECT_DIR=$(git rev-parse --show-toplevel)

$PROJECT_DIR/scripts/clean.sh
$PROJECT_DIR/scripts/document.sh

mkdir $PROJECT_DIR/build

cp $PROJECT_DIR/package.json $PROJECT_DIR/build/package.json
cp $PROJECT_DIR/README.md $PROJECT_DIR/build/README.md

$PROJECT_DIR/node_modules/.bin/babel src \
--out-dir build \
--source-maps inline \
--ignore "src/test.js" \
--ignore "src/*.test.js" \
"$@"
2 changes: 0 additions & 2 deletions scripts/clean.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@
set -e

PROJECT_DIR=$(git rev-parse --show-toplevel)
BIN_DIR=$(npm bin)
JSDOC="$BIN_DIR/jsdoc"

rm -rf $PROJECT_DIR/build
rm -rf $PROJECT_DIR/coverage
Expand Down
10 changes: 7 additions & 3 deletions scripts/cover.sh
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
#!/bin/sh
#!/bin/bash

yarn clean
./node_modules/.bin/jest --coverage --runInBand
set -e

PROJECT_DIR=$(git rev-parse --show-toplevel)

$PROJECT_DIR/scripts/clean.sh
$PROJECT_DIR/scripts/test.sh --coverage "$@"
8 changes: 4 additions & 4 deletions scripts/deploy.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

set -e

yarn cover
yarn build
yarn document
PROJECT_DIR=$(git rev-parse --show-toplevel)

cp README.md build/README.md
$PROJECT_DIR/scripts/cover.sh
$PROJECT_DIR/scripts/document.sh
$PROJECT_DIR/scripts/build.sh

yarn publish --access public --cwd build --no-git-tag-version
10 changes: 8 additions & 2 deletions scripts/document.sh
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,15 @@ set -e
PROJECT_DIR=$(git rev-parse --show-toplevel)
BIN_DIR=$(npm bin)
JSDOC="$BIN_DIR/jsdoc"
OPTIONS="--module-index-format none --global-index-format none --example-lang js --heading-depth 3"

$JSDOC -c $PROJECT_DIR/jsdoc.config.json "$@"
./node_modules/.bin/jsdoc2md src/index.js src/QueryStringError.js --module-index-format none --global-index-format none --example-lang js --heading-depth 1 > README.md
./scripts/postProcessReadme.js README.md
cat $PROJECT_DIR/src/README.md > $PROJECT_DIR/README.md

echo "" >> $PROJECT_DIR/README.md
echo "## API" >> $PROJECT_DIR/README.md
echo "" >> $PROJECT_DIR/README.md

$PROJECT_DIR/node_modules/.bin/jsdoc2md $PROJECT_DIR/src/index.js $PROJECT_DIR/src/QueryStringError.js $OPTIONS >> $PROJECT_DIR/README.md

$PROJECT_DIR/scripts/postProcessReadme.js $PROJECT_DIR/README.md
8 changes: 6 additions & 2 deletions scripts/lint.sh
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
#!/bin/sh
#!/bin/bash

./node_modules/.bin/eslint src
set -e

PROJECT_DIR=$(git rev-parse --show-toplevel)

$PROJECT_DIR/node_modules/.bin/eslint $PROJECT_DIR/src "$@"
28 changes: 19 additions & 9 deletions scripts/postProcessReadme.js
Original file line number Diff line number Diff line change
Expand Up @@ -8,32 +8,42 @@ const contents = String(fs.readFileSync(filename));
const lines = contents.split('\n');

let isIndex = false;
let isApiSection = false;

const newContents = lines.filter((l, index) => {
if (l.startsWith('# ') && lines[index + 2] && lines[index + 2].startsWith('* [')) {
isIndex = true;
}

if (l.startsWith('* [')) {
const newContents = lines.filter((l) => {
if (l.startsWith('* [@')) {
isIndex = true;
} else if (l === '') {
isIndex = false;
}

return !isIndex;
}).filter((l) => {
return !l.startsWith('### @');
}).map((l, index, lines) => {
const innerClassOfPrefix = '**Kind**: inner class of';

if (l.startsWith('## ')) {
if (l.startsWith('#### @')) {
return l + ' ⏏';
}

if (l.startsWith(innerClassOfPrefix)) {
return '**Kind**: Exported class' + l.slice(innerClassOfPrefix.length);
return '**Kind**: Exported class';
}

return l;
}).map((l, index, lines) => {
if (l === '## API') {
isApiSection = true;
return l;
}

if (isApiSection && l.startsWith('##')) {
return l.slice(1);
}

return l;
}).join('\n').replace(/\n\n+/gm, '\n\n');;
}).join('\n').replace(/\n\n+/gm, '\n\n').replace('&commat;', '@').replace('&sol;', '/');

fs.writeFileSync(filename, newContents);

10 changes: 7 additions & 3 deletions scripts/test.sh
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
#!/bin/sh
#!/bin/bash

yarn clean
./node_modules/.bin/jest --runInBand
set -e

PROJECT_DIR=$(git rev-parse --show-toplevel)

$PROJECT_DIR/scripts/clean.sh
$PROJECT_DIR/node_modules/.bin/jest --runInBand "$@"
77 changes: 77 additions & 0 deletions src/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# @zakkudo/query-string

Make working with url query-strings enjoyable.

[![Build Status](https://travis-ci.org/zakkudo/query-string.svg?branch=master)](https://travis-ci.org/zakkudo/query-string)
[![Coverage Status](https://coveralls.io/repos/github/zakkudo/query-string/badge.svg?branch=master)](https://coveralls.io/github/zakkudo/query-string?branch=master)
[![Known Vulnerabilities](https://snyk.io/test/github/zakkudo/query-string/badge.svg)](https://snyk.io/test/github/zakkudo/query-string)

## Why use this?

- Consistancy with simplicity
- The instance acts like a plain-old-object
- `JSON.stringify()` will serialize it to json like it was a normal object
- Casting to a string will format it to be directly usable in a query
Update the properties after initialization and the serialization will reflect the updates
- Complex params are automatically serialized and deserialized from json

## Install

```console
# Install using npm
npm install @zakkudo/query-string
```

``` console
# Install using yarn
yarn add @zakkudo/query-string
```

## Examples

### Initializing with an object
```javascript
import QueryString from '@zakkudo/query-string';

const query = new QueryString({
page: 3,
title: 'awesomeness',
complex: {'test': 'value'}
});

String(query) // '?page=3&title=awesomeness&complex=%7B%22test%22%3A%22value%22%7D&'
query.toString() // '?page=3&title=awesomeness&complex=%7B%22test%22%3A%22value%22%7D&'

const url = `http://example${query}` //Automatically serializes correctly

const url = `http://example${query}` //Automatically serializes correctly with changes
```

### Initializing with a URL and making changes dynamically
```javascript
import QueryString from '@zakkudo/query-string';

const query = new QueryString('http://example?page=3&title=awesomeness');

delete query.page;

String(query) // '?title=awesomeness'
query.toString() // '?title=awesomeness'
```

### Error handling
```javascript
import QueryString from '@zakkudo/query-string';
import QueryStringError from '@zakkudo/query-string/QueryStringError';

try {
const query = new QueryString('http://invalid.com/?first=1?second=2')
} catch(e) {
if (e instanceof QueryStringError) {
console.error(e.message); // Trying to add duplicate query param when already exists
} else {
throw e;
}
}
```

10 changes: 0 additions & 10 deletions src/getTypeName.js

This file was deleted.

Loading

0 comments on commit f5797ce

Please sign in to comment.