@osdlc/frontmatter-lossless 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- 2f3fc7c: Add `newShape(opts?)`, with its options type `NewShapeOptions`: the
+  `NoteShape` for a new note, one with no source text to `split`. Both fences
+  end in `eol` (`'\n'` by default, or `'\r\n'`), and `bom` (default `false`)
+  adds a byte-order mark. `compose(yaml, body, newShape())` gives
+  `---\n<yaml>\n---\n<body>`. Pass the YAML text the way `split` returns it,
+  without the line break before the closing fence. Until now there was no
+  supported way to write a new note, because a `NoteShape` must not be built by
+  hand.
+- 2f3fc7c: `Split` has a new `unterminated` field. It is `true` when a note starts with a
+  valid opening fence (`---` and a line break, after an optional BOM) and no
+  closing `---` line follows. `yaml` is still `null` and `body` the whole text,
+  as before, so only a caller that wants to report the note as malformed needs
+  to read it. Until now such a caller had to repeat the opening-fence check
+  itself.
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -60,6 +60,8 @@ compose(yaml, body, shape) === note // true
   found only when the note starts with `---` and a line break, after an
   optional BOM, and is closed by `---` alone on a line. Anything else,
   including a block with no closing fence, is body. It never throws.
+  `unterminated` is `true` when the note opens a block that never closes, so
+  a caller can report that note as malformed rather than read it as body.
 - `compose(frontmatter, body, shape)` rebuilds the note. `frontmatter` is
   `null` for no block, `''` for an empty block, or the YAML text. Passing back
   what `split` returned gives the original text.
@@ -67,11 +69,24 @@ compose(yaml, body, shape) === note // true
   `'\r\n'`), `closeEol` (a `CloseEol`, which can also be `''` when the note
   ends at the closing fence) and `closeSep`. Take it from `split` and pass it
   to `compose`. Do not build one by hand: a minor release may add a field.
+- `newShape(opts?)` returns the `NoteShape` for a new note that has no source
+  text to split. Its `NewShapeOptions` are `eol` (`'\n'` by default, or
+  `'\r\n'`) for both fences and `bom` (`false` by default). Pass the YAML
+  text the way `split` returns it, without the line break before the closing
+  fence: trim the trailing newline a YAML serializer adds.
 - `splitLenient(content)` reads hand-written input that `split` rejects: blank lines or indentation
   before the opening fence, and trailing spaces on the fence lines. The closing fence must not be
   indented. It returns a `LenientSplit` (`yaml` and `body`), or `null` when there is no block. It
   keeps no framing, so use it to read, not to rewrite.
 
+```ts
+import { compose, newShape } from '@osdlc/frontmatter-lossless'
+
+const yaml = 'title: New\ntags: [a]\n' // as a YAML serializer writes it
+compose(yaml.replace(/\n$/, ''), '# New\n', newShape())
+// '---\ntitle: New\ntags: [a]\n---\n# New\n'
+```
+
 Offsets are JavaScript string indices (UTF-16 code units):
 `src.slice(yamlRange.start, yamlRange.end) === yaml` and
 `src.slice(bodyStart) === body`.

package/dist/index.d.ts

@@ -46,9 +46,10 @@ export type CloseEol = '' | '\n' | '\r\n';
  * file whose fences were `---\r\n`, and now every line of the note shows as
  * changed in git. The fences are data too.
  *
- * Take it from {@link split} and pass it back to {@link compose}; do not build
- * one by hand. A minor release may add a field, which would break an object
- * literal typed as `NoteShape`.
+ * Take it from {@link split} and pass it back to {@link compose}, or, for a
+ * new note with no source text, from {@link newShape}. Do not build one by
+ * hand: a minor release may add a field, which would break an object literal
+ * typed as `NoteShape`.
  */
 export interface NoteShape {
     /** The byte-order mark, if the file had one. */
@@ -91,6 +92,22 @@ export interface Split {
     readonly bodyStart: number;
     /** The framing to restore when writing this note back. */
     readonly shape: NoteShape;
+    /** `true` when the note opens a frontmatter block that never closes: it
+     *  starts with a valid opening fence (`---` and a line break, after an
+     *  optional BOM) and no closing `---` line follows. `yaml` is still `null`
+     *  and `body` the whole text, as for a note with no block, so a projection
+     *  keeps going; a caller that holds authored notes to a contract can read
+     *  this to report the note as malformed instead. `false` otherwise.
+     *  Optional so a `Split` built by hand, such as a test fake, still type-checks;
+     *  {@link split} always sets it. */
+    readonly unterminated?: boolean | undefined;
+}
+/** Options for {@link newShape}. */
+export interface NewShapeOptions {
+    /** Line ending of both fences. Default `'\n'`. */
+    readonly eol?: OpenEol | undefined;
+    /** Whether the note starts with a byte-order mark. Default `false`. */
+    readonly bom?: boolean | undefined;
 }
 /** The result of a tolerant read-only split: see {@link splitLenient}. */
 export interface LenientSplit {
@@ -105,7 +122,8 @@ export interface LenientSplit {
  *
  * Frontmatter is recognised only when the document begins with `---\n` (or
  * `---\r\n`, or either after a BOM) and is closed by `---` alone on a line.
- * Anything else — including a missing terminator — is body. A leading BOM is
+ * Anything else — including a missing terminator — is body; a missing
+ * terminator also sets {@link Split.unterminated}. A leading BOM is
  * framing: it is recorded in {@link Split.shape} and excluded from both
  * `yaml` and `body`, never duplicated into the content.
  */
@@ -120,6 +138,30 @@ export declare function split(src: string): Split;
  * reproduces `src` byte for byte for every shape.
  */
 export declare function compose(frontmatter: string | null, body: string, shape: NoteShape): string;
+/**
+ * The shape for a new note, one with no source text to {@link split}: both
+ * fences end in `eol` and the closing fence has its line ending. It stays
+ * valid when {@link NoteShape} gains fields, which an object literal would
+ * not.
+ *
+ * `compose(yaml, body, newShape())` gives `---\n<yaml>\n---\n<body>`. The
+ * `yaml` argument is the text between the fences as {@link split} returns
+ * it: without the line break before the closing fence. A YAML serializer's
+ * output usually ends in one, so drop it first, or the block ends in a
+ * blank line. With `eol: '\r\n'`, `compose` writes the fences as CRLF and
+ * the yaml text keeps its own line endings, so end its lines in `\r\n` and
+ * the text itself in `\r`, as {@link split} returns a CRLF block.
+ *
+ * An empty `yaml` gives `---\n\n---\n`: since the closing fence keeps its
+ * line break, the block holds one blank line. It round-trips through
+ * {@link split}.
+ *
+ * @example
+ * ```ts
+ * compose('title: A', '# A\n', newShape()) // '---\ntitle: A\n---\n# A\n'
+ * ```
+ */
+export declare function newShape(opts?: NewShapeOptions): NoteShape;
 /**
  * A tolerant, read-only frontmatter read for possibly-sloppy input.
  *

package/dist/index.js

@@ -34,7 +34,8 @@ const BOM = '\uFEFF';
  *
  * Frontmatter is recognised only when the document begins with `---\n` (or
  * `---\r\n`, or either after a BOM) and is closed by `---` alone on a line.
- * Anything else — including a missing terminator — is body. A leading BOM is
+ * Anything else — including a missing terminator — is body; a missing
+ * terminator also sets {@link Split.unterminated}. A leading BOM is
  * framing: it is recorded in {@link Split.shape} and excluded from both
  * `yaml` and `body`, never duplicated into the content.
  */
@@ -42,12 +43,13 @@ export function split(src) {
     const bom = src.startsWith(BOM);
     const rest = bom ? src.slice(BOM.length) : src;
     const offset = bom ? BOM.length : 0;
-    const noFrontmatter = () => ({
+    const noFrontmatter = (unterminated) => ({
         yaml: null,
         yamlRange: { start: 0, end: 0 },
         body: rest,
         bodyStart: offset,
         shape: { bom, openEol: '\n', closeEol: '\n', closeSep: true },
+        unterminated,
     });
     let afterMarker;
     let markerLen;
@@ -63,7 +65,7 @@ export function split(src) {
         openEol = '\r\n';
     }
     else {
-        return noFrontmatter();
+        return noFrontmatter(false);
     }
     const yamlStart = offset + markerLen;
     // Empty frontmatter: the closing fence sits directly after the opener.
@@ -78,6 +80,7 @@ export function split(src) {
                 body: afterMarker.slice(len),
                 bodyStart: yamlStart + len,
                 shape: { bom, openEol, closeEol, closeSep: false },
+                unterminated: false,
             };
         }
     }
@@ -88,13 +91,15 @@ export function split(src) {
             body: '',
             bodyStart: src.length,
             shape: { bom, openEol, closeEol: '', closeSep: false },
+            unterminated: false,
         };
     }
     let searchStart = 0;
     for (;;) {
         const found = afterMarker.indexOf('\n---', searchStart);
+        // An opening fence with no closing one.
         if (found === -1)
-            return noFrontmatter();
+            return noFrontmatter(true);
         const dashesStart = found + 1;
         const afterDashes = dashesStart + 3;
         const yamlLen = found;
@@ -123,6 +128,7 @@ export function split(src) {
             body: afterMarker.slice(bodyRel),
             bodyStart: yamlStart + bodyRel,
             shape: { bom, openEol, closeEol, closeSep: true },
+            unterminated: false,
         };
     }
 }
@@ -158,6 +164,33 @@ export function compose(frontmatter, body, shape) {
     out += '---' + (shape.closeEol === '' && body !== '' ? shape.openEol : shape.closeEol) + body;
     return out;
 }
+/**
+ * The shape for a new note, one with no source text to {@link split}: both
+ * fences end in `eol` and the closing fence has its line ending. It stays
+ * valid when {@link NoteShape} gains fields, which an object literal would
+ * not.
+ *
+ * `compose(yaml, body, newShape())` gives `---\n<yaml>\n---\n<body>`. The
+ * `yaml` argument is the text between the fences as {@link split} returns
+ * it: without the line break before the closing fence. A YAML serializer's
+ * output usually ends in one, so drop it first, or the block ends in a
+ * blank line. With `eol: '\r\n'`, `compose` writes the fences as CRLF and
+ * the yaml text keeps its own line endings, so end its lines in `\r\n` and
+ * the text itself in `\r`, as {@link split} returns a CRLF block.
+ *
+ * An empty `yaml` gives `---\n\n---\n`: since the closing fence keeps its
+ * line break, the block holds one blank line. It round-trips through
+ * {@link split}.
+ *
+ * @example
+ * ```ts
+ * compose('title: A', '# A\n', newShape()) // '---\ntitle: A\n---\n# A\n'
+ * ```
+ */
+export function newShape(opts = {}) {
+    const eol = opts.eol ?? '\n';
+    return { bom: opts.bom ?? false, openEol: eol, closeEol: eol, closeSep: true };
+}
 /**
  * A tolerant, read-only frontmatter read for possibly-sloppy input.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/frontmatter-lossless",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Byte-exact Markdown frontmatter framing: split a note into verbatim YAML and body with source offsets, and put it back together byte for byte. BOM, CRLF and fence bytes are kept. No dependencies.",
   "license": "MIT OR Apache-2.0",
   "author": "sksizer",