refactor: change -> modification

packages/nest/readme.md

@@ -92,6 +92,24 @@ Scenario 3:<br />
 const fs = await FileSystem.fromCID(fsPointer, { blockstore })
 ```
 
+## Commit verification
+
+This exists so you can approve modifications to the file system.
+
+```ts
+import { Modification } from '@wnfs-wg/nest'
+
+const fs = FileSystem.create({
+  blockstore,
+  onCommit: (modifications: Modification[]): { commit: boolean } => {
+    // For example, check if I have access to all paths.
+    const satisfied = modifications.every(m => ALLOWED_PATHS.includes( Path.toPosix(m.path) ))
+    if (satisfied) return { commit: true }
+    else return { commit: false }
+  }
+})
+```
+
 ## Docs
 
 Check <https://fission-codes.github.io/stack>

packages/nest/src/class.ts

@@ -625,7 +625,7 @@ export class FileSystem {
     mutationOptions: MutationOptions = {}
   ): Promise<
     | {
-        changes: Modification[]
+        modifications: Modification[]
         dataRoot: CID
       }
     | NOOP
@@ -639,7 +639,7 @@ export class FileSystem {
     const commitResult = await TransactionContext.commit(context)
     if (commitResult === 'no-op') return 'no-op'
 
-    const { changes, privateNodes, rootTree } = commitResult
+    const { modifications, privateNodes, rootTree } = commitResult
 
     this.#privateNodes = privateNodes
     this.#rootTree = rootTree
@@ -650,7 +650,7 @@ export class FileSystem {
     // Emit events
     await this.#eventEmitter.emit('commit', {
       dataRoot,
-      modifications: [...changes],
+      modifications: [...modifications],
     })
 
     // Publish
@@ -663,7 +663,7 @@ export class FileSystem {
 
     // Fin
     return {
-      changes,
+      modifications,
       dataRoot,
     }
   }

packages/nest/src/root-tree.ts

@@ -11,12 +11,12 @@ export abstract class RootTree {
   abstract privateForest(): PrivateForest
   abstract replacePrivateForest(
     forest: PrivateForest,
-    changes: Modification[]
+    modifications: Modification[]
   ): Promise<RootTree>
   abstract publicRoot(): PublicDirectory
   abstract replacePublicRoot(
     dir: PublicDirectory,
-    changes: Modification[]
+    modifications: Modification[]
   ): Promise<RootTree>
 
   abstract clone(): RootTree

packages/nest/src/root-tree/basic.ts

@@ -150,7 +150,7 @@ export class BasicRootTree implements RootTree {
 
   async replacePrivateForest(
     forest: PrivateForest,
-    _changes: Modification[]
+    _modifications: Modification[]
   ): Promise<RootTree> {
     return new BasicRootTree({
       blockstore: this.#blockstore,
@@ -169,7 +169,7 @@ export class BasicRootTree implements RootTree {
 
   async replacePublicRoot(
     dir: PublicDirectory,
-    changes: Modification[]
+    modifications: Modification[]
   ): Promise<RootTree> {
     const treeWithNewPublicRoot = new BasicRootTree({
       blockstore: this.#blockstore,
@@ -181,26 +181,26 @@ export class BasicRootTree implements RootTree {
       version: this.#version,
     })
 
-    const unixTree = await changes.reduce(async (oldRootPromise, change) => {
+    const unixTree = await modifications.reduce(async (oldRootPromise, mod) => {
       const oldRoot = await oldRootPromise
 
-      if (!Path.isPartition('public', change.path)) {
+      if (!Path.isPartition('public', mod.path)) {
         return oldRoot
       }
 
-      const path = Path.removePartition(change.path)
+      const path = Path.removePartition(mod.path)
 
-      if (change.type === 'removed') {
+      if (mod.type === 'removed') {
         return await Unix.removeNodeFromTree(oldRoot, path, this.#blockstore)
       }
 
       const contentCID =
-        Path.isFile(change.path) &&
-        Path.isPartitionedNonEmpty<Path.Public>(change.path)
+        Path.isFile(mod.path) &&
+        Path.isPartitionedNonEmpty<Path.Public>(mod.path)
           ? await References.contentCID(
               this.#blockstore,
               treeWithNewPublicRoot,
-              change.path
+              mod.path
             )
           : undefined
 

packages/nest/src/transaction.ts

@@ -52,7 +52,7 @@ export class TransactionContext {
   #privateNodes: MountedPrivateNodes
   #rootTree: RootTree
 
-  readonly #changes: Set<{
+  readonly #modifications: Set<{
     type: MutationType
     path: Path.Distinctive<Partitioned<Partition>>
   }>
@@ -71,13 +71,13 @@ export class TransactionContext {
     this.#rng = rng
     this.#rootTree = rootTree
 
-    this.#changes = new Set()
+    this.#modifications = new Set()
   }
 
   /** @internal */
   static async commit(context: TransactionContext): Promise<
     | {
-        changes: Array<{
+        modifications: Array<{
           path: Path.Distinctive<Partitioned<Partition>>
           type: MutationType
         }>
@@ -86,23 +86,23 @@ export class TransactionContext {
       }
     | NOOP
   > {
-    const changes = [...context.#changes]
+    const modifications = [...context.#modifications]
 
     // Verify
-    const { commit } = await context.#onCommit([...changes])
+    const { commit } = await context.#onCommit([...modifications])
     if (!commit) return 'no-op'
 
     // Private forest
-    const newForest = await changes.reduce(
-      async (oldForestPromise, change): Promise<PrivateForest> => {
+    const newForest = await modifications.reduce(
+      async (oldForestPromise, mod): Promise<PrivateForest> => {
         const oldForest = await oldForestPromise
 
-        if (!Path.isPartition('private', change.path)) {
+        if (!Path.isPartition('private', mod.path)) {
           return oldForest
         }
 
         const maybeNode = findPrivateNode(
-          change.path as Path.Distinctive<Path.Partitioned<Path.Private>>,
+          mod.path as Path.Distinctive<Path.Partitioned<Path.Private>>,
           context.#privateNodes
         )
 
@@ -119,12 +119,12 @@ export class TransactionContext {
     // Replace forest
     const rootTree = await context.#rootTree.replacePrivateForest(
       newForest,
-      changes
+      modifications
     )
 
     // Fin
     return {
-      changes: changes,
+      modifications: modifications,
       privateNodes: context.#privateNodes,
       rootTree: rootTree,
     }
@@ -568,7 +568,7 @@ export class TransactionContext {
     mut: Mutations.Public,
     mutType: MutationType
   ): Promise<void> {
-    const change = {
+    const mod = {
       type: mutType,
       path: path,
     }
@@ -581,11 +581,11 @@ export class TransactionContext {
 
     // Replace public root
     this.#rootTree = await this.#rootTree.replacePublicRoot(result.rootDir, [
-      change,
+      mod,
     ])
 
     // Mark node as changed
-    this.#changes.add(change)
+    this.#modifications.add(mod)
   }
 
   async #privateMutation(
@@ -609,7 +609,7 @@ export class TransactionContext {
     })
 
     // Mark node as changed
-    this.#changes.add(change)
+    this.#modifications.add(change)
 
     // Replace forest
     this.#rootTree = await this.#rootTree.replacePrivateForest(result.forest, [

packages/nest/src/types.ts

@@ -7,7 +7,7 @@ export type AnySupportedDataType<V> =
   | string
 
 export type CommitVerifier = (
-  changes: Modification[]
+  modifications: Modification[]
 ) => Promise<{ commit: boolean }>
 
 export type DataType = 'bytes' | 'json' | 'utf8'

packages/nest/test/class.test.ts

@@ -1035,7 +1035,7 @@ describe('File System Class', () => {
     fs = await FileSystem.create({
       blockstore,
       ...fsOpts,
-      onCommit: async (_changes: Modification[]) => ({ commit: false }),
+      onCommit: async (_modifications: Modification[]) => ({ commit: false }),
     })
 
     mounts = await fs.mountPrivateNodes([{ path: Path.root() }])