Skip to content

Commit 9f1b2cb

Browse files
jonlucajonluca
committed
chore(readme): clean up readme, clean up deprecated info, modernize examples
1 parent 55ee6f3 commit 9f1b2cb

File tree

5 files changed

+71
-197
lines changed

5 files changed

+71
-197
lines changed

‎README.md

+63-78
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,23 @@
99
[![License](https://img.shields.io/npm/l/@apidevtools/json-schema-ref-parser.svg)](LICENSE)
1010
[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/APIDevTools/json-schema-ref-parser)
1111

12+
Installation
13+
--------------------------
14+
Install using [npm](https://docs.npmjs.com/about-npm/):
15+
16+
```bash
17+
npm install @apidevtools/json-schema-ref-parser
18+
yarn add @apidevtools/json-schema-ref-parser
19+
bun add @apidevtools/json-schema-ref-parser
20+
```
21+
1222
The Problem:
1323
--------------------------
14-
You've got a JSON Schema with `$ref` pointers to other files and/or URLs. Maybe you know all the referenced files ahead of time. Maybe you don't. Maybe some are local files, and others are remote URLs. Maybe they are a mix of JSON and YAML format. Maybe some of the files contain cross-references to each other.
24+
You've got a JSON Schema with `$ref` pointers to other files and/or URLs. Maybe you know all the referenced files ahead
25+
of time. Maybe you don't. Maybe some are local files, and others are remote URLs. Maybe they are a mix of JSON and YAML
26+
format. Maybe some of the files contain cross-references to each other.
1527

16-
```javascript
28+
```json
1729
{
1830
"definitions": {
1931
"person": {
@@ -36,144 +48,117 @@ You've got a JSON Schema with `$ref` pointers to other files and/or URLs. Maybe
3648
}
3749
```
3850

39-
4051
The Solution:
4152
--------------------------
42-
JSON Schema $Ref Parser is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most complex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) and gives you simple, straightforward JavaScript objects.
53+
JSON Schema $Ref Parser is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)
54+
and [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most
55+
complex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) and gives you simple, straightforward
56+
JavaScript objects.
4357

4458
- Use **JSON** or **YAML** schemas — or even a mix of both!
45-
- Supports `$ref` pointers to external files and URLs, as well as [custom sources](https://apitools.dev/json-schema-ref-parser/docs/plugins/resolvers.html) such as databases
46-
- Can [bundle](https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#bundlepath-options-callback) multiple files into a single schema that only has _internal_ `$ref` pointers
47-
- Can [dereference](https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#dereferencepath-options-callback) your schema, producing a plain-old JavaScript object that's easy to work with
48-
- Supports [circular references](https://apitools.dev/json-schema-ref-parser/docs/#circular-refs), nested references, back-references, and cross-references between files
49-
- Maintains object reference equality — `$ref` pointers to the same value always resolve to the same object instance
50-
- Tested in Node v10, v12, & v14, and all major web browsers on Windows, Mac, and Linux
51-
59+
- Supports `$ref` pointers to external files and URLs, as well
60+
as [custom sources](https://apitools.dev/json-schema-ref-parser/docs/plugins/resolvers.html) such as databases
61+
- Can [bundle](https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#bundlepath-options-callback) multiple
62+
files into a single schema that only has _internal_ `$ref` pointers
63+
- Can [dereference](https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#dereferencepath-options-callback)
64+
your schema, producing a plain-old JavaScript object that's easy to work with
65+
- Supports [circular references](https://apitools.dev/json-schema-ref-parser/docs/#circular-refs), nested references,
66+
back-references, and cross-references between files
67+
- Maintains object reference equality — `$ref` pointers to the same value always resolve to the same object
68+
instance
69+
- Compatible with Node LTS and beyond, and all major web browsers on Windows, Mac, and Linux
5270

5371
Example
5472
--------------------------
5573

5674
```javascript
57-
$RefParser.dereference(mySchema, (err, schema) => {
58-
if (err) {
59-
console.error(err);
60-
}
61-
else {
62-
// `schema` is just a normal JavaScript object that contains your entire JSON Schema,
63-
// including referenced files, combined into a single object
64-
console.log(schema.definitions.person.properties.firstName);
65-
}
66-
})
67-
```
68-
69-
Or use `async`/`await` syntax instead. The following example is the same as above:
75+
import $RefParser from "@apidevtools/json-schema-ref-parser";
7076

71-
```javascript
7277
try {
7378
let schema = await $RefParser.dereference(mySchema);
7479
console.log(schema.definitions.person.properties.firstName);
75-
}
76-
catch(err) {
80+
} catch (err) {
7781
console.error(err);
7882
}
7983
```
8084

8185
For more detailed examples, please see the [API Documentation](https://apitools.dev/json-schema-ref-parser/docs/)
8286

8387

84-
85-
Installation
88+
Polyfills
8689
--------------------------
87-
Install using [npm](https://docs.npmjs.com/about-npm/):
8890

89-
```bash
90-
npm install @apidevtools/json-schema-ref-parser
91-
```
9291

92+
If you are using Node.js < 18, you'll need a polyfill for `fetch`,
93+
like [node-fetch](https://github.com/node-fetch/node-fetch):
9394

94-
95-
Usage
96-
--------------------------
97-
When using JSON Schema $Ref Parser in Node.js apps, you'll probably want to use **CommonJS** syntax:
98-
99-
```javascript
100-
const $RefParser = require("@apidevtools/json-schema-ref-parser");
101-
```
102-
103-
When using a transpiler such as [Babel](https://babeljs.io/) or [TypeScript](https://www.typescriptlang.org/), or a bundler such as [Webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/), you can use **ECMAScript modules** syntax instead:
104-
105-
```javascript
106-
import $RefParser from "@apidevtools/json-schema-ref-parser";
107-
```
108-
109-
If you are using Node.js < 18, you'll need a polyfill for `fetch`, like [node-fetch](https://github.com/node-fetch/node-fetch):
11095
```javascript
11196
import fetch from "node-fetch";
11297

11398
globalThis.fetch = fetch;
11499
```
115100

116-
117-
118101
Browser support
119102
--------------------------
120-
JSON Schema $Ref Parser supports recent versions of every major web browser. Older browsers may require [Babel](https://babeljs.io/) and/or [polyfills](https://babeljs.io/docs/en/next/babel-polyfill).
121-
122-
To use JSON Schema $Ref Parser in a browser, you'll need to use a bundling tool such as [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Parcel](https://parceljs.org/), or [Browserify](http://browserify.org/). Some bundlers may require a bit of configuration, such as setting `browser: true` in [rollup-plugin-resolve](https://github.com/rollup/rollup-plugin-node-resolve).
103+
JSON Schema $Ref Parser supports recent versions of every major web browser. Older browsers may
104+
require [Babel](https://babeljs.io/) and/or [polyfills](https://babeljs.io/docs/en/next/babel-polyfill).
123105

106+
To use JSON Schema $Ref Parser in a browser, you'll need to use a bundling tool such
107+
as [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Parcel](https://parceljs.org/),
108+
or [Browserify](http://browserify.org/). Some bundlers may require a bit of configuration, such as
109+
setting `browser: true` in [rollup-plugin-resolve](https://github.com/rollup/rollup-plugin-node-resolve).
124110

125111
#### Webpack 5
126-
Webpack 5 has dropped the default export of node core modules in favour of polyfills, you'll need to set them up yourself ( after npm-installing them )
112+
113+
Webpack 5 has dropped the default export of node core modules in favour of polyfills, you'll need to set them up
114+
yourself ( after npm-installing them )
127115
Edit your `webpack.config.js` :
116+
128117
```js
129-
config.resolve.fallback = {
130-
"path": require.resolve("path-browserify"),
131-
'util': require.resolve('util/'),
132-
'fs': require.resolve('browserify-fs'),
133-
"buffer": require.resolve("buffer/"),
134-
"http": require.resolve("stream-http"),
135-
"https": require.resolve("https-browserify"),
136-
"url": require.resolve("url"),
137-
}
118+
config.resolve.fallback = {
119+
"path": require.resolve("path-browserify"),
120+
'fs': require.resolve('browserify-fs')
121+
}
138122

139-
config.plugins.push(
140-
new webpack.ProvidePlugin({
141-
Buffer: [ 'buffer', 'Buffer']
142-
})
143-
)
123+
config.plugins.push(
124+
new webpack.ProvidePlugin({
125+
Buffer: ['buffer', 'Buffer']
126+
})
127+
)
144128

145129
```
146130

147-
148131
API Documentation
149132
--------------------------
150133
Full API documentation is available [right here](https://apitools.dev/json-schema-ref-parser/docs/)
151134

152135

153-
154136
Contributing
155137
--------------------------
156-
I welcome any contributions, enhancements, and bug-fixes. [Open an issue](https://github.com/APIDevTools/json-schema-ref-parser/issues) on GitHub and [submit a pull request](https://github.com/APIDevTools/json-schema-ref-parser/pulls).
138+
I welcome any contributions, enhancements, and
139+
bug-fixes. [Open an issue](https://github.com/APIDevTools/json-schema-ref-parser/issues) on GitHub
140+
and [submit a pull request](https://github.com/APIDevTools/json-schema-ref-parser/pulls).
157141

158142
#### Building/Testing
143+
159144
To build/test the project locally on your computer:
160145

161146
1. __Clone this repo__<br>
162-
`git clone https://github.com/APIDevTools/json-schema-ref-parser.git`
147+
`git clone https://github.com/APIDevTools/json-schema-ref-parser.git`
163148

164149
2. __Install dependencies__<br>
165-
`npm install`
150+
`yarn install`
166151

167152
3. __Run the tests__<br>
168-
`npm test`
169-
170-
153+
`yarn test`
171154

172155
License
173156
--------------------------
174157
JSON Schema $Ref Parser is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
175158

176-
This package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/APIDevTools/json-schema-ref-parser) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
159+
This package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a
160+
tree**](https://plant.treeware.earth/APIDevTools/json-schema-ref-parser) to thank us for our work. By contributing to
161+
the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
177162

178163

179164

‎lib/dereference.ts

+5-7
Original file line numberDiff line numberDiff line change
@@ -159,16 +159,14 @@ function crawl(
159159
*/
160160
function dereference$Ref(
161161
$ref: any,
162-
path: any,
163-
pathFromRoot: any,
164-
parents: any,
162+
path: string,
163+
pathFromRoot: string,
164+
parents: Set<any>,
165165
processedObjects: any,
166166
dereferencedCache: any,
167-
$refs: any,
168-
options: any,
167+
$refs: $Refs,
168+
options: $RefParserOptions,
169169
) {
170-
// console.log('Dereferencing $ref pointer "%s" at %s', $ref.$ref, path);
171-
172170
const isExternalRef = $Ref.isExternal$Ref($ref);
173171
const shouldResolveOnCwd = isExternalRef && options?.dereference.externalReferenceResolution === "root";
174172
const $refPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);

‎lib/pointer.ts

+2-1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import type $RefParserOptions from "./options.js";
33
import $Ref from "./ref.js";
44
import * as url from "./util/url.js";
55
import { JSONParserError, InvalidPointerError, MissingPointerError, isHandledError } from "./util/errors.js";
6+
67
const slashes = /\//g;
78
const tildes = /~/g;
89
const escapedSlash = /~1/g;
@@ -57,7 +58,7 @@ class Pointer {
5758
*/
5859
indirections: number;
5960

60-
constructor($ref: any, path: any, friendlyPath?: string) {
61+
constructor($ref: $Ref, path: string, friendlyPath?: string) {
6162
this.$ref = $ref;
6263

6364
this.path = path;

0 commit comments

Comments
 (0)