[pull] master from nodeca:master

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.3.0] - 2026-08-14
+
+This release focuses on reworking the documentation and making small
+architectural improvements before moving forward.
+
+### Added
+- Added completely new documentation.
+- Exported `DUMP_SCHEMA`, the default schema used by the dumper.
+- Added `YAMLException.throwAt()` for throwing an error at a source position.
+
+### Changed
+- Changed flat constant exports to grouped exports: `EVENT_ID`, `SCALAR_STYLE`,
+  `COLLECTION_STYLE`, and `CHOMPING_MODE`, along with their value types. The old
+  exports are still preserved, but deprecated.
+- Made `identify` mandatory for custom tag definitions. Use
+  `identify: () => false` for load-only tags.
+
+### Deprecated
+- Deprecated flat constant exports. Use grouped ones instead.
+
+### Removed
+- Removed the `MERGE_KEY` export (not used anymore after last fixes).
+
+### Fixed
+- Validate `<<` sequence items at merge time, so aliased merge sources are
+  checked too.
+- Resolve `<<` outside of a mapping key as the plain string `'<<'`, matching
+  v4, instead of leaking an internal symbol into the result.
+
+
 ## [5.2.3] - 2026-08-01
 
 ### Fixed
@@ -171,7 +201,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [4.0.0] - 2021-01-03
 ### Changed
-- Check migration guide in [docs](docs/) for details of all breaking changes.
+- Check migration guide for details of all breaking changes.
 - Breaking: "unsafe" tags `!!js/function`, `!!js/regexp`, `!!js/undefined` are
   moved to [js-yaml-js-types](https://github.com/nodeca/js-yaml-js-types) package.
 - Breaking: removed `safe*` functions. Use `load`, `loadAll`, `dump`
@@ -693,6 +723,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - First public release
 
 
+[5.3.0]: https://github.com/nodeca/js-yaml/compare/5.2.3...5.3.0
 [5.2.3]: https://github.com/nodeca/js-yaml/compare/5.2.2...5.2.3
 [5.2.2]: https://github.com/nodeca/js-yaml/compare/5.2.1...5.2.2
 [5.2.1]: https://github.com/nodeca/js-yaml/compare/5.2.0...5.2.1

README.md

@@ -1,211 +1,47 @@
-JS-YAML - YAML 1.2 parser / writer for JavaScript
-=================================================
+# js-yaml
 
 [![CI](https://github.com/nodeca/js-yaml/actions/workflows/ci.yml/badge.svg)](https://github.com/nodeca/js-yaml/actions/workflows/ci.yml)
 [![NPM version](https://img.shields.io/npm/v/js-yaml.svg)](https://www.npmjs.org/package/js-yaml)
 
-__[Online Demo](https://nodeca.github.io/js-yaml/)__
+> YAML 1.2 parser and serializer for JavaScript.
 
+__[Online demo](https://nodeca.github.io/js-yaml/)__
 
-A fast and complete [YAML](https://yaml.org/) parser and writer for JavaScript.
-Supports both the 1.2 and 1.1 specs, and passes the entire
-[YAML Test Suite](https://github.com/yaml/yaml-test-suite).
+- Supports the YAML 1.2 and YAML 1.1 specifications.
+- Passes the entire [YAML Test Suite](https://github.com/yaml/yaml-test-suite).
 
 
-Installation
-------------
+> [!NOTE]
+> If you are upgrading from v4, see the [v5 migration guide](docs/migrate_v4_to_v5.md).
 
-```
-npm install js-yaml
-```
+### [Documentation >>](https://nodeca.github.io/js-yaml/doc/)
 
-Upgrading from v4? See the [v5 migration guide](docs/migrate_v4_to_v5.md).
 
+##### Install
+
+```bash
+npm install js-yaml
+```
 
-API
----
 
-Here we cover the most useful methods. If you need advanced details (such as
-creating your own tags), see the [examples](examples/) for more info.
+##### Usage
 
-``` javascript
+```js
 import { load } from 'js-yaml'
-import { readFileSync } from 'node:fs'
 
-// Get document, or throw exception on error
 try {
-  const doc = load(readFileSync('example.yml', 'utf8'))
-  console.log(doc)
+  const document = load('greeting: hello')
+  console.log(document.greeting)
 } catch (e) {
-  console.log(e)
+  console.error(e)
 }
 ```
 
+```js
+import { dump } from 'js-yaml'
 
-### load (string [ , options ])
-
-Parses `string` as a single YAML document. Throws `YAMLException` on error.
-This function **does not** understand multi-document or empty sources; it throws
-an exception on those.
-
-> [!WARNING]
-> When processing untrusted input, see the
-> [security considerations](docs/safety.md).
-
-options:
-
-- `filename` _(default: null)_ - string to be used as a file path in error
-  messages.
-- `schema` _(default: `CORE_SCHEMA`)_ - specifies a schema to use.
-  - `FAILSAFE_SCHEMA` - only strings, arrays and plain objects.
-  - `JSON_SCHEMA` - all JSON-supported types.
-  - `CORE_SCHEMA` - a superset of `JSON_SCHEMA`, accepting more notations for
-    the same types.
-  - `YAML11_SCHEMA` - adds the legacy YAML 1.1 types (`!!binary`, `!!timestamp`,
-    `!!omap`, `!!pairs`, `!!set`, merge keys `<<`, and the broader 1.1 scalar
-    notations).
-- `json` _(default: false)_ - compatibility with `JSON.parse` behaviour. If
-  `true`, duplicate keys in a mapping override values rather than throwing an
-  error.
-- `maxDepth` _(default: 100)_ - limits the nesting depth for collections (does
-  not take aliases into account).
-- `maxTotalMergeKeys` _(default: 10000)_ - limits the total number of keys
-  processed by merge (`<<`) across one `load()` / `loadAll()` call. Set to `-1`
-  to disable.
-- `maxAliases` _(default: -1)_ - limits the number of alias nodes (`*ref`) per
-  document. Set to `0` to reject all aliases, or to `-1` for no limit.
-
-> [!NOTE]
->
-> The default `CORE_SCHEMA` comes without the `!!merge` tag. You can easily
-> enable it if needed:
->
-> ``` javascript
-> import { load, CORE_SCHEMA, mergeTag } from 'js-yaml'
->
-> load(data, { schema: CORE_SCHEMA.withTags(mergeTag) })
-> ```
-
-> [!WARNING]
->
-> The default `mapTag` is `{}`-object based and does not allow complex keys
-> (objects, arrays and so on). That's an intentional choice for convenience.
-> Also, non-string scalar keys, such as `null`, numbers or booleans, are
-> converted to strings.
->
-> In the rare cases where you really need complex keys, use `realMapTag` in the
-> schema instead. It stores any key exactly as provided, at the cost of less
-> convenient access.
-
-See [examples](examples/) for advanced customization approaches.
-
-
-### loadAll (string [, options ])
-
-Same as `load()`, but understands multi-document sources. Returns an array of
-documents.
-
-``` javascript
-import { loadAll } from 'js-yaml'
-
-console.log(loadAll(data))
-```
-
-
-### dump (object [ , options ])
-
-Serializes `object` as a YAML document. By default it can dump every supported
-YAML type, so it throws an exception if you try to dump regexps or functions.
-However, you can disable exceptions by setting the `skipInvalid` option to
-`true`.
-
-options:
-
-- `indent` _(default: 2)_ - indentation width to use (in spaces).
-- `flowLevel` _(default: -1)_ - nesting level at which collections switch from
-  block to flow style (`-1` means never).
-- `seqNoIndent` _(default: false)_ - when `true`, does not add an indentation
-  level to array elements, `␣␣- 1` => `- 1`.
-- `seqInlineFirst` _(default: true)_ - when `true`, allows a nested collection
-  to start on the same line after `-`, `-\n  - 1` => `- - 1`.
-- `skipInvalid` _(default: false)_ - do not throw on invalid types (such as a
-  function in the schema). Invalid mapping pairs and sequence items are skipped;
-  `undefined` sequence items are serialized as `null`.
-- `schema` _(default: a `YAML11_SCHEMA`-based schema)_ - specifies a schema to
-  use.
-- `sortKeys` _(default: `false`)_ - if `true`, sort keys when dumping YAML. If a
-  function, use the function to sort the keys.
-- `lineWidth` _(default: `80`)_ - sets the max line width. Set `-1` for unlimited
-  width.
-- `noRefs` _(default: `false`)_ - if `true`, don't convert duplicate objects into
-  references; inline them instead.
-- `quoteStyle` _(`single` or `double`, default: `single`)_ - quoting style to use
-  when a string needs quotes.
-- `forceQuotes` _(default: `false`)_ - if `true`, quote all non-key strings,
-  using `quoteStyle`.
-- `flowBracketPadding` _(default: `false`)_ - add spaces inside flow collection
-  brackets, `{a: 1}` => `{ a: 1 }`.
-- `flowSkipCommaSpace` _(default: `false`)_ - omit the space after commas in
-  flow collections, `[1, 2]` => `[1,2]`.
-- `flowSkipColonSpace` _(default: `false`)_ - omit the space after `:` in flow
-  mappings, `{a: 1}` => `{a:1}`.
-- `quoteFlowKeys` _(default: `false`)_ - quote flow mapping keys, `{a: 1}` =>
-  `{"a": 1}`.
-- `tagBeforeAnchor` _(default: `false`)_ - print an explicit tag before an
-  anchor, `&ref_0 !!set` => `!!set &ref_0`.
-- `transform` - a function `(documents: Document[]) => void` that can mutate the
-  generated AST before it is rendered.
-
-See [examples](examples/) for advanced customization approaches.
-
-
-Supported YAML types
---------------------
-
-The list of standard YAML tags and corresponding JavaScript types. See also
-[YAML tag discussion](https://pyyaml.org/wiki/YAMLTagDiscussion) and
-[YAML types repository](https://yaml.org/type/).
-
-```
-!!null ''                   # null
-!!bool 'true'               # bool
-!!int '3...'                # number
-!!float '3.14...'           # number
-!!str '...'                 # string
-!!seq [ ... ]               # array
-!!map { ... }               # object (or Map)
-```
-
-The types below are only available in `YAML11_SCHEMA` (not in the default
-`CORE_SCHEMA`):
-
-```
-!!binary '...base64...'     # Uint8Array
-!!timestamp 'YYYY-...'      # date
-!!set { ... }               # Set
-
-# Legacy YAML 1.1 compatibility only; these types cannot be dumped.
-!!omap [ ... ]              # array of key-value pairs
-!!pairs [ ... ]             # array of array pairs
-```
-
-To preserve complex keys in the first position of a `!!pairs` item, replace
-the default object-based map with `realMapTag` in the schema.
-
-**JavaScript-specific tags**
-
-See [js-yaml-js-types](https://github.com/nodeca/js-yaml-js-types) for
-extra types.
-
-
-CLI
----
-
-This can be useful sometimes for a quick check.
-
-```
-npx js-yaml -h
+const source = dump({ greeting: 'hello' })
+console.log(source)
 ```
 
-Note: the CLI script comes with minimal options, and there are no big plans to
-extend it.
+[More usage examples](docs/usage.md).