Skip to content

Commit 4ed8ce9

Browse files
SkySailsSkySails
committed
docs: improve documentation and split contrib docs
1 parent 4707703 commit 4ed8ce9

File tree

3 files changed

+96
-60
lines changed

3 files changed

+96
-60
lines changed

‎CONTRIBUTING.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Contribution guidelines
2+
3+
## Commands
4+
5+
```bash
6+
npm start # or yarn start
7+
```
8+
9+
This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`.
10+
11+
To do a one-off build, use `npm run build` or `yarn build`.
12+
13+
To run tests, use `npm test` or `yarn test`.
14+
15+
## Configuration
16+
17+
Code quality will be set up using `prettier`, `husky`, and `lint-staged`.
18+
19+
### Jest
20+
21+
Jest tests are set up to run with `npm test` or `yarn test`.
22+
23+
### Rollup
24+
25+
This project uses [Rollup](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details.
26+
27+
### TypeScript
28+
29+
`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `jsx`.
30+
31+
## Continuous Integration
32+
33+
### GitHub Actions
34+
35+
Two actions are added by default:
36+
37+
- `main` which installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix
38+
39+
## Optimizations
40+
41+
You can do development-only optimizations by using the `__DEV__` global variable.
42+
43+
```js
44+
// ./types/index.d.ts
45+
declare var __DEV__: boolean;
46+
47+
// inside your code...
48+
if (__DEV__) {
49+
console.log('foo');
50+
}
51+
```
52+
53+
## Module Formats
54+
55+
CJS, ESModules, and UMD module formats are supported.
56+
57+
The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found.

‎README.md

+28-58
Original file line numberDiff line numberDiff line change
@@ -57,73 +57,43 @@ glc.error('An error ocurred in the pizza component!', {
5757
});
5858
```
5959

60-
## Available methods
61-
62-
The `GraylogClient` contains multiple convenience methods mapping directly towards syslog's [severity levels](https://en.wikipedia.org/wiki/Syslog#Severity_level).
63-
64-
| Method | Severity | Description | Condition |
65-
| --------- | ------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
66-
| emergency | Emergency | System is unusable | A panic condition.[[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
67-
| alert | Alert | Action must be taken immediately | A condition that should be corrected immediately, such as a corrupted system database.[[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
68-
| critical | Critical | Critical conditions | Hard device errors.[[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
69-
| error | Error | Error conditions | |
70-
| warning | Warning | Warning conditions | |
71-
| notice | Notice | Normal but significant conditions | Conditions that are not error conditions, but that may require special handling.[[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
72-
| info | Informational | Informational messages | |
73-
| debug | Debug | Debug-level messages | Messages that contain information normally of use only when debugging a program.[[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
74-
75-
## Commands
76-
77-
```bash
78-
npm start # or yarn start
79-
```
80-
81-
This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`.
82-
83-
To do a one-off build, use `npm run build` or `yarn build`.
84-
85-
To run tests, use `npm test` or `yarn test`.
60+
## Constructor
8661

87-
## Configuration
62+
| Property | Type | Description | Required |
63+
| -------- | ------ | ---------------------------------------------------------------------- | -------- |
64+
| server | string | The endpoint to which the requests should be sent, including protocol. | yes |
65+
| source | string | The client from which the logs are sent. | yes |
8866

89-
Code quality will be set up using `prettier`, `husky`, and `lint-staged`.
67+
### Typescript
9068

91-
### Jest
69+
If typescript is used, an optional type generic may be passed to the constructor. This can be used to type the extra information sent with each request (see the [Advanced Example](#advanced) for an example implementation), but is not required.
9270

93-
Jest tests are set up to run with `npm test` or `yarn test`.
94-
95-
### Rollup
96-
97-
This project uses [Rollup](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details.
98-
99-
### TypeScript
100-
101-
`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `jsx`.
102-
103-
## Continuous Integration
104-
105-
### GitHub Actions
106-
107-
Two actions are added by default:
71+
## Available methods
10872

109-
- `main` which installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix
73+
The `GraylogClient` contains multiple convenience methods mapping directly towards syslog's [severity levels](https://en.wikipedia.org/wiki/Syslog#Severity_level).
11074

111-
## Optimizations
75+
| Method | Severity | Description | Condition |
76+
| --------- | ------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77+
| emergency | Emergency | System is unusable | A panic condition. [[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
78+
| alert | Alert | Action must be taken immediately | A condition that should be corrected immediately, such as a corrupted system database. [[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
79+
| critical | Critical | Critical conditions | Hard device errors. [[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
80+
| error | Error | Error conditions | |
81+
| warning | Warning | Warning conditions | |
82+
| notice | Notice | Normal but significant conditions | Conditions that are not error conditions, but that may require special handling. [[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
83+
| info | Informational | Informational messages | |
84+
| debug | Debug | Debug-level messages | Messages that contain information normally of use only when debugging a program. [[1]](https://pubs.opengroup.org/onlinepubs/009695399/functions/syslog.html) |
11285

113-
You can do development-only optimizations by using the `__DEV__` global variable.
86+
Each method may be called with two parameters in accordance with the specification below.
11487

115-
```js
116-
// ./types/index.d.ts
117-
declare var __DEV__: boolean;
88+
| Parameter | Type | Description | Required |
89+
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
90+
| message | string | The short (summary) message to display in Graylog. | yes |
91+
| extras | object | Any extra information, not including the source client. This object may be typed using a generic in the constructor, see [Constructor](#typescript). | no |
11892

119-
// inside your code...
120-
if (__DEV__) {
121-
console.log('foo');
122-
}
123-
```
93+
## Contributing
12494

125-
## Module Formats
95+
For guidelines and useful information, please see [CONTRIBUTING.md](https://github.com/Navigraph/graylog-client/blob/master/CONTRIBUTING.md)
12696

127-
CJS, ESModules, and UMD module formats are supported.
97+
## License
12898

129-
The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found.
99+
[MIT](https://github.com/Navigraph/graylog-client/blob/master/LICENSE)

‎src/index.ts

+11-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
interface GraylogClientOptions {
2+
/** The endpoint to which the requests should be sent, including protocol. */
23
server: string;
4+
/** The client from which the logs are sent. */
35
source: string;
46
}
57

@@ -30,7 +32,7 @@ enum Level {
3032
}
3133

3234
// prettier-ignore
33-
export default class GraylogClient<ExtrasType = { [key: string] : string }> {
35+
export default class GraylogClient<ExtrasType = {}> {
3436
public server: string;
3537
public source: string;
3638

@@ -68,28 +70,35 @@ export default class GraylogClient<ExtrasType = { [key: string] : string }> {
6870
console.error(err.stack);
6971
});
7072
}
71-
73+
/** Sends a log with emergency (level 0) severity. */
7274
emergency(message: string, extras?: ExtrasType) {
7375
return this.sendRequest({ short_message: message, level: Level.emergency, ...extras });
7476
}
77+
/** Sends a log with alert (level 1) severity. */
7578
alert(message: string, extras?: ExtrasType) {
7679
return this.sendRequest({ short_message: message, level: Level.alert, ...extras });
7780
}
81+
/** Sends a log with critical (level 2) severity. */
7882
critical(message: string, extras?: ExtrasType) {
7983
return this.sendRequest({ short_message: message, level: Level.critical, ...extras });
8084
}
85+
/** Sends a log with error (level 3) severity. */
8186
error(message: string, extras?: ExtrasType) {
8287
return this.sendRequest({ short_message: message, level: Level.error, ...extras });
8388
}
89+
/** Sends a log with warning (level 4) severity. */
8490
warning(message: string, extras?: ExtrasType) {
8591
return this.sendRequest({ short_message: message, level: Level.warning, ...extras });
8692
}
93+
/** Sends a log with notice (level 5) severity. */
8794
notice(message: string, extras?: ExtrasType) {
8895
return this.sendRequest({ short_message: message, level: Level.notice, ...extras });
8996
}
97+
/** Sends a log with info (level 6) severity. */
9098
info(message: string, extras?: ExtrasType) {
9199
return this.sendRequest({ short_message: message, level: Level.info, ...extras });
92100
}
101+
/** Sends a log with debug (level 7) severity. */
93102
debug(message: string, extras?: ExtrasType) {
94103
return this.sendRequest({ short_message: message, level: Level.debug, ...extras });
95104
}

0 commit comments

Comments
 (0)