markdown-patch 0.1.0

package/src/tests/sample.patch.heading.replace.md

@@ -0,0 +1,81 @@
+---
+aliases:
+- Structured Markdown Patch
+project-type: Technical
+repository: https://github.com/coddingtonbear/markdown-patch
+---
+
+# Overview
+Beep Boop
+# Problems
+- ~~It would be nice for the mechanism to be able to handle something like `upsert` for frontmatter fields.  See [[#^e6068e]] in addition to what we already support [[#^259a73]].~~
+	- This was solved by making every content block directly-addressable.  All interactions treat the document as a key-value mapping.
+- ~~You can't use our earlier header delimiter `::` in an HTTP header; how did I not notice that?  I've had a [conversation with ChatGPT](https://chatgpt.com/share/117b262a-f534-40e6-bc05-287758706f34) to land on a choice of `@#@` instead, but there aren't obvious good options.  See [[#^1d6271]]~~
+	- I changed my mind in the end and went with the more-likely-to-collide-but-at-least-not-bizarre `///`.
+- Should we allow partial matches?  The pros are that it would make the usual, garden path of just wanting to push content into a section very easy.  The cons are that it makes it kind of unclear what's going to happen when you do an `upsert` or `insert` for a particular value.  (See [[#^bfec1f]] for more).
+
+# Actions
+| Name      | Description                                                                                                                                                                       | Heading? | Frontmatter? | Block               |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------- |
+| `update`  | Find the referenced `target` and replace the content at that region.                                                                                                              | ✅        | ✅            | ✅                   |
+| `append`  | Find the referenced `target` and add content to the end of its region.                                                                                                            | ✅        | ✅            | ✅                   |
+| `prepend` | Find the referenced `target` and add content to the beginning of its region.                                                                                                      | ✅        | ✅            | ✅                   |
+| `insert`  | Find the path leading to the referenced `target` and add the specified content under a the specified name. This will create a new header or frontmatter field if necessary.       | ✅        | ✅            | ❌[^block-ambiguity] |
+| `upsert`  | Find the path leading to the referenced `target` and either replace the content under the specified name, or add new content with a new header or frontmatter field if necessary. | ✅        | ✅            | ❌[^block-ambiguity] |
+
+^2c67a6
+
+# Headers
+| Header             | Explanation                                                                                                                                                                                    |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Target-Type`      | `heading`, `block`, `frontmatter`                                                                                                                                                              |
+| `Target`           | Name of the target:<br>- `heading`: The `///`-delimited path to the heading to replace the content of.  E.g. `Page Targets///Block///Use Cases`.  This value should be URL-encoded.            |
+| `Target-Delimiter` | By default, we use `///` to delimit a `Target`, but it's remotely possible that this value might be present in a header.  If it is, you can specify a different delimiter to use for `Target`. |
+
+^1d6271
+
+# Page Targets
+
+## Heading
+
+| Heading       | Value                                                 |
+| ------------- | ----------------------------------------------------- |
+| `Target-Type` | `heading`                                             |
+| `Target`      | The path to the heading you would like to append to.  |
+
+^bfec1f
+
+| Position | Where                                                          |
+| -------- | -------------------------------------------------------------- |
+| Start    | Beginning of line immediately following line named by heading  |
+| End      | Last newline before heading of same or higher priority or EOF. |
+|          |                                                                |
+Unlike with [[#Heading]], this targets the *content* of the heading and does not include the heading iself.
+- ✅: ...replacing the content specified by a particular heading.
+- ✅: ...appending content to a block specified by a particular heading.
+## Block
+| Position | Where                                                  |
+| -------- | ------------------------------------------------------ |
+| Start    | Beginning of line for specified block.                 |
+| End      | Last character (including newline) of specified block. |
+A "Block" in Obsidian can be any *block*-type element.  This might mean a paragraph, but it could also mean a table, but how block references are marked differs in Obsidian depending upon what kind of block is being marked.
+### Use Cases
+- ✅: ...replacing the content specified by a particular block ID.
+	- I want to be able to replace a whole table or whole paragraph with new content.
+- ✅: ...appending content to a block specified by a particular block ID.
+	- I want to be able to add new rows to an existing table.
+	- I want to be able to add new content to the end of a line.
+
+## Frontmatter Field
+
+| Position | Where                                                                    |
+| -------- | ------------------------------------------------------------------------ |
+| Start    | First character of content referenced by a particular frontmatter field. |
+| End      | Last character of content referenced by a particular frontmatter field.  |
+### Use Cases
+- ✅: ...appending content to an existing frontmatter field.
+- ✅: ...replacing the content of an existing frontmatter field. ^259a73
+- ✅: ...adding a new frontmatter field. ^e6068e
+## Document Properties (Exploratory)
+
+[^block-ambiguity]: There is currently no obvious place to plop a block were we to create a new one.  So, I might implement this such that these actions *work*, but will just add the block to the end of a file.  This isn't great, but it's at least consistent?

package/src/tests/sample.patch.heading.trimTargetWhitespace.append.md

@@ -0,0 +1,80 @@
+---
+aliases:
+- Structured Markdown Patch
+project-type: Technical
+repository: https://github.com/coddingtonbear/markdown-patch
+---
+
+# Overview
+I came up with this project for supporting [[Obsidian Local Rest API]] (and via that [[Obsidian Web]]) because I often need to shove data into Markdown documents for posterity, but want to be able to do that programmatically with more care than just shoving content to the end of a file.
+# Problems
+- ~~It would be nice for the mechanism to be able to handle something like `upsert` for frontmatter fields.  See [[#^e6068e]] in addition to what we already support [[#^259a73]].~~
+	- This was solved by making every content block directly-addressable.  All interactions treat the document as a key-value mapping.
+- ~~You can't use our earlier header delimiter `::` in an HTTP header; how did I not notice that?  I've had a [conversation with ChatGPT](https://chatgpt.com/share/117b262a-f534-40e6-bc05-287758706f34) to land on a choice of `@#@` instead, but there aren't obvious good options.  See [[#^1d6271]]~~
+	- I changed my mind in the end and went with the more-likely-to-collide-but-at-least-not-bizarre `///`.
+- Should we allow partial matches?  The pros are that it would make the usual, garden path of just wanting to push content into a section very easy.  The cons are that it makes it kind of unclear what's going to happen when you do an `upsert` or `insert` for a particular value.  (See [[#^bfec1f]] for more).Beep Boop
+# Actions
+| Name      | Description                                                                                                                                                                       | Heading? | Frontmatter? | Block               |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------- |
+| `update`  | Find the referenced `target` and replace the content at that region.                                                                                                              | ✅        | ✅            | ✅                   |
+| `append`  | Find the referenced `target` and add content to the end of its region.                                                                                                            | ✅        | ✅            | ✅                   |
+| `prepend` | Find the referenced `target` and add content to the beginning of its region.                                                                                                      | ✅        | ✅            | ✅                   |
+| `insert`  | Find the path leading to the referenced `target` and add the specified content under a the specified name. This will create a new header or frontmatter field if necessary.       | ✅        | ✅            | ❌[^block-ambiguity] |
+| `upsert`  | Find the path leading to the referenced `target` and either replace the content under the specified name, or add new content with a new header or frontmatter field if necessary. | ✅        | ✅            | ❌[^block-ambiguity] |
+
+^2c67a6
+
+# Headers
+| Header             | Explanation                                                                                                                                                                                    |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Target-Type`      | `heading`, `block`, `frontmatter`                                                                                                                                                              |
+| `Target`           | Name of the target:<br>- `heading`: The `///`-delimited path to the heading to replace the content of.  E.g. `Page Targets///Block///Use Cases`.  This value should be URL-encoded.            |
+| `Target-Delimiter` | By default, we use `///` to delimit a `Target`, but it's remotely possible that this value might be present in a header.  If it is, you can specify a different delimiter to use for `Target`. |
+
+^1d6271
+
+# Page Targets
+
+## Heading
+
+| Heading       | Value                                                 |
+| ------------- | ----------------------------------------------------- |
+| `Target-Type` | `heading`                                             |
+| `Target`      | The path to the heading you would like to append to.  |
+
+^bfec1f
+
+| Position | Where                                                          |
+| -------- | -------------------------------------------------------------- |
+| Start    | Beginning of line immediately following line named by heading  |
+| End      | Last newline before heading of same or higher priority or EOF. |
+|          |                                                                |
+Unlike with [[#Heading]], this targets the *content* of the heading and does not include the heading iself.
+- ✅: ...replacing the content specified by a particular heading.
+- ✅: ...appending content to a block specified by a particular heading.
+## Block
+| Position | Where                                                  |
+| -------- | ------------------------------------------------------ |
+| Start    | Beginning of line for specified block.                 |
+| End      | Last character (including newline) of specified block. |
+A "Block" in Obsidian can be any *block*-type element.  This might mean a paragraph, but it could also mean a table, but how block references are marked differs in Obsidian depending upon what kind of block is being marked.
+### Use Cases
+- ✅: ...replacing the content specified by a particular block ID.
+	- I want to be able to replace a whole table or whole paragraph with new content.
+- ✅: ...appending content to a block specified by a particular block ID.
+	- I want to be able to add new rows to an existing table.
+	- I want to be able to add new content to the end of a line.
+
+## Frontmatter Field
+
+| Position | Where                                                                    |
+| -------- | ------------------------------------------------------------------------ |
+| Start    | First character of content referenced by a particular frontmatter field. |
+| End      | Last character of content referenced by a particular frontmatter field.  |
+### Use Cases
+- ✅: ...appending content to an existing frontmatter field.
+- ✅: ...replacing the content of an existing frontmatter field. ^259a73
+- ✅: ...adding a new frontmatter field. ^e6068e
+## Document Properties (Exploratory)
+
+[^block-ambiguity]: There is currently no obvious place to plop a block were we to create a new one.  So, I might implement this such that these actions *work*, but will just add the block to the end of a file.  This isn't great, but it's at least consistent?

package/src/tests/sample.patch.heading.trimTargetWhitespace.prepend.md

@@ -0,0 +1,80 @@
+---
+aliases:
+- Structured Markdown Patch
+project-type: Technical
+repository: https://github.com/coddingtonbear/markdown-patch
+---
+
+# Overview
+I came up with this project for supporting [[Obsidian Local Rest API]] (and via that [[Obsidian Web]]) because I often need to shove data into Markdown documents for posterity, but want to be able to do that programmatically with more care than just shoving content to the end of a file.
+# Problems
+- ~~It would be nice for the mechanism to be able to handle something like `upsert` for frontmatter fields.  See [[#^e6068e]] in addition to what we already support [[#^259a73]].~~
+	- This was solved by making every content block directly-addressable.  All interactions treat the document as a key-value mapping.
+- ~~You can't use our earlier header delimiter `::` in an HTTP header; how did I not notice that?  I've had a [conversation with ChatGPT](https://chatgpt.com/share/117b262a-f534-40e6-bc05-287758706f34) to land on a choice of `@#@` instead, but there aren't obvious good options.  See [[#^1d6271]]~~
+	- I changed my mind in the end and went with the more-likely-to-collide-but-at-least-not-bizarre `///`.
+- Should we allow partial matches?  The pros are that it would make the usual, garden path of just wanting to push content into a section very easy.  The cons are that it makes it kind of unclear what's going to happen when you do an `upsert` or `insert` for a particular value.  (See [[#^bfec1f]] for more).
+
+# Actions
+| Name      | Description                                                                                                                                                                       | Heading? | Frontmatter? | Block               |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------- |
+| `update`  | Find the referenced `target` and replace the content at that region.                                                                                                              | ✅        | ✅            | ✅                   |
+| `append`  | Find the referenced `target` and add content to the end of its region.                                                                                                            | ✅        | ✅            | ✅                   |
+| `prepend` | Find the referenced `target` and add content to the beginning of its region.                                                                                                      | ✅        | ✅            | ✅                   |
+| `insert`  | Find the path leading to the referenced `target` and add the specified content under a the specified name. This will create a new header or frontmatter field if necessary.       | ✅        | ✅            | ❌[^block-ambiguity] |
+| `upsert`  | Find the path leading to the referenced `target` and either replace the content under the specified name, or add new content with a new header or frontmatter field if necessary. | ✅        | ✅            | ❌[^block-ambiguity] |
+
+^2c67a6
+
+# Headers
+| Header             | Explanation                                                                                                                                                                                    |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Target-Type`      | `heading`, `block`, `frontmatter`                                                                                                                                                              |
+| `Target`           | Name of the target:<br>- `heading`: The `///`-delimited path to the heading to replace the content of.  E.g. `Page Targets///Block///Use Cases`.  This value should be URL-encoded.            |
+| `Target-Delimiter` | By default, we use `///` to delimit a `Target`, but it's remotely possible that this value might be present in a header.  If it is, you can specify a different delimiter to use for `Target`. |
+
+^1d6271
+
+# Page Targets
+
+## Heading
+
+| Heading       | Value                                                 |
+| ------------- | ----------------------------------------------------- |
+| `Target-Type` | `heading`                                             |
+| `Target`      | The path to the heading you would like to append to.  |
+
+^bfec1f
+
+| Position | Where                                                          |
+| -------- | -------------------------------------------------------------- |
+| Start    | Beginning of line immediately following line named by heading  |
+| End      | Last newline before heading of same or higher priority or EOF. |
+|          |                                                                |
+Unlike with [[#Heading]], this targets the *content* of the heading and does not include the heading iself.
+- ✅: ...replacing the content specified by a particular heading.
+- ✅: ...appending content to a block specified by a particular heading.
+## Block
+| Position | Where                                                  |
+| -------- | ------------------------------------------------------ |
+| Start    | Beginning of line for specified block.                 |
+| End      | Last character (including newline) of specified block. |
+A "Block" in Obsidian can be any *block*-type element.  This might mean a paragraph, but it could also mean a table, but how block references are marked differs in Obsidian depending upon what kind of block is being marked.
+### Use Cases
+- ✅: ...replacing the content specified by a particular block ID.
+	- I want to be able to replace a whole table or whole paragraph with new content.
+- ✅: ...appending content to a block specified by a particular block ID.
+	- I want to be able to add new rows to an existing table.
+	- I want to be able to add new content to the end of a line.
+
+## Frontmatter Field
+
+| Position | Where                                                                    |
+| -------- | ------------------------------------------------------------------------ |
+| Start    | First character of content referenced by a particular frontmatter field. |
+| End      | Last character of content referenced by a particular frontmatter field.  |
+### Use Cases
+- ✅: ...appending content to an existing frontmatter field.
+- ✅: ...replacing the content of an existing frontmatter field. ^259a73
+- ✅: ...adding a new frontmatter field. ^e6068e
+## Document Properties (Exploratory)
+Beep Boop[^block-ambiguity]: There is currently no obvious place to plop a block were we to create a new one.  So, I might implement this such that these actions *work*, but will just add the block to the end of a file.  This isn't great, but it's at least consistent?

package/src/types.ts

@@ -0,0 +1,155 @@
+export interface DocumentRange {
+  start: number;
+  end: number;
+}
+
+export interface DocumentMapMarkerContentPair {
+  marker: DocumentRange;
+  content: DocumentRange;
+}
+
+export interface HeadingMarkerContentPair extends DocumentMapMarkerContentPair {
+  level: number;
+}
+
+export interface DocumentMap {
+  heading: Record<string, HeadingMarkerContentPair>;
+  block: Record<string, DocumentMapMarkerContentPair>;
+}
+
+export type PatchTargetType = "heading" | "block";
+
+export type PatchOperation = "replace" | "prepend" | "append";
+
+export interface BasePatchInstructionTarget {
+  targetType: PatchTargetType;
+  target: any;
+}
+
+export interface BasePatchInstructionOperation {
+  operation: string;
+}
+
+export interface BaseHeadingPatchInstruction
+  extends BasePatchInstructionTarget {
+  targetType: "heading";
+  target: string[] | null;
+}
+
+export interface BaseBlockPatchInstruction extends BasePatchInstructionTarget {
+  targetType: "block";
+  target: string;
+}
+
+export interface NonExtendingPatchInstruction
+  extends BasePatchInstructionOperation {}
+
+export interface ExtendingPatchInstruction
+  extends BasePatchInstructionOperation {
+  /** Trim whitepsace from target before joining with content
+   *
+   * - For `prepend`: Trims content from the beginning of
+   *   the target content.
+   * - For `append`: Trims content from the end of the target
+   *   content.  Your content should probably end in a newline
+   *   in this case, or the trailing heading will no longer
+   *   be the start of its own line
+   */
+  trimTargetWhitespace?: boolean;
+  /** Apply patch even if content already exists at target
+   *
+   * By default, we will fail to apply a patch if the supplied
+   * content is found anywhere in your target content.  If you
+   * would instead like the patch to occur, regardless of whether
+   * it appears the content is already there, you can set
+   * `applyIfContentPreexists` to `true`.
+   */
+  applyIfContentPreexists?: boolean;
+}
+
+export interface StringContent {
+  content: string;
+}
+
+export interface TableRowsContent {
+  targetBlockTypeBehavior: "table";
+  content: string[][];
+}
+
+export interface PrependHeadingPatchInstruction
+  extends ExtendingPatchInstruction,
+    BaseHeadingPatchInstruction,
+    StringContent {
+  operation: "prepend";
+}
+
+export interface AppendHeadingPatchInstruction
+  extends ExtendingPatchInstruction,
+    BaseHeadingPatchInstruction,
+    StringContent {
+  operation: "append";
+}
+
+export interface ReplaceHeadingPatchInstruction
+  extends NonExtendingPatchInstruction,
+    BaseHeadingPatchInstruction,
+    StringContent {
+  operation: "replace";
+}
+
+export interface PrependBlockPatchInstruction
+  extends ExtendingPatchInstruction,
+    BaseBlockPatchInstruction,
+    StringContent {
+  operation: "prepend";
+}
+
+export interface AppendBlockPatchInstruction
+  extends ExtendingPatchInstruction,
+    BaseBlockPatchInstruction,
+    StringContent {
+  operation: "append";
+}
+
+export interface ReplaceBlockPatchInstruction
+  extends NonExtendingPatchInstruction,
+    BaseBlockPatchInstruction,
+    StringContent {
+  operation: "replace";
+}
+
+export interface PrependTableRowsBlockPatchInstruction
+  extends ExtendingPatchInstruction,
+    BaseBlockPatchInstruction,
+    TableRowsContent {
+  operation: "prepend";
+}
+
+export interface AppendTableRowsBlockPatchInstruction
+  extends ExtendingPatchInstruction,
+    BaseBlockPatchInstruction,
+    TableRowsContent {
+  operation: "append";
+}
+
+export interface ReplaceTableRowsBlockPatchInstruction
+  extends NonExtendingPatchInstruction,
+    BaseBlockPatchInstruction,
+    TableRowsContent {
+  operation: "replace";
+}
+
+export type HeadingPatchInstruction =
+  | PrependHeadingPatchInstruction
+  | AppendHeadingPatchInstruction
+  | ReplaceHeadingPatchInstruction;
+
+export type BlockPatchInstruction =
+  | PrependBlockPatchInstruction
+  | AppendBlockPatchInstruction
+  | ReplaceBlockPatchInstruction
+  | PrependTableRowsBlockPatchInstruction
+  | AppendTableRowsBlockPatchInstruction
+  | ReplaceTableRowsBlockPatchInstruction;
+
+export type PatchInstruction = HeadingPatchInstruction | BlockPatchInstruction;

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "@tsconfig/node16/tsconfig.json",
+  "compilerOptions": {
+    "module": "ESNext",                                /* Specify what module code is generated. */
+    "target": "ES2020",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    "moduleResolution": "node",                     /* Specify how TypeScript looks up a file from a given module specifier. */
+    "outDir": "./dist",                                   /* Specify an output folder for all emitted files. */
+    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+    "strict": true,                                      /* Enable all strict type-checking options. */
+    "skipLibCheck": true,                                 /* Skip type checking all .d.ts files. */
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "ts-node": {
+    "transpileOnly": true
+  }
+}