release v0.12.0

* update vitepress

* add docs for combined converter and update documentation for converters

* update documentation

* update package files

* rename stringify to unify

Author: CordlessWool

adapters/in-memory/package.json

@@ -1,14 +1,14 @@
 {
 	"name": "@loom-io/in-memory-adapter",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"main": "dist/exports/lib.js",
 	"types": "dist/exports/lib.d.ts",
 	"author": "Cotton Coding",
 	"description": "A file system wrapper for Node.js and Bun",
 	"keywords": [
+		"loom-io",
 		"in-memory",
-		"adapter",
-		"@loom-io"
+		"adapter"
 	],
 	"files": [
 		"dist"

adapters/minio/package.json

@@ -1,16 +1,16 @@
 {
 	"name": "@loom-io/minio-s3-adapter",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"main": "dist/exports/lib.js",
 	"types": "dist/exports/lib.d.ts",
 	"author": "Cotton Coding",
 	"description": "A file system wrapper for Node.js and Bun",
 	"keywords": [
+		"loom-io",
 		"adapter",
 		"minio",
 		"s3",
-		"file",
-		"@loom-io"
+		"file"
 	],
 	"files": [
 		"dist"

adapters/node-fs/package.json

@@ -1,18 +1,18 @@
 {
 	"name": "@loom-io/node-filesystem-adapter",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"main": "dist/exports/lib.js",
 	"types": "dist/exports/lib.d.ts",
 	"author": "Cotton Coding",
 	"description": "A file system wrapper for Node.js and Bun",
 	"keywords": [
+		"loom-io",
 		"fs",
 		"filesystem",
 		"node",
 		"bun",
 		"nodejs",
-		"adapter",
-		"@loom-io"
+		"adapter"
 	],
 	"files": [
 		"dist"

documentation/.vitepress/config.mts

@@ -1,55 +1,56 @@
-import { defineConfig } from 'vitepress'
+import { defineConfig } from "vitepress";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  title: "loom-io",
-  description: "weave your data access",
-  lastUpdated: true,
-  themeConfig: {
-    logo: "/loom-io.png",
-    // https://vitepress.dev/reference/default-theme-config
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Docs', link: '/core/intro' }
-    ],
-    sidebar: [
-      {
-        text: 'Getting Started',
-        items: [
-          { text: 'Introduction', link: '/core/intro' },
-          { text: 'Setup', link: '/core/setup' },
-          { text: 'Examples', link: '/core/examples' }
-        ]
-      },
-      {
-        text: 'Source Adapter',
-        items: [
-          { text: 'In-Memory', link: '/adapter/in-memory-adapter' },
-          { text: 'Filesystem', link: '/adapter/node-filesystem-adapter' },
-          { text: 'S3-Minio', link: '/adapter/minio-s3-adapter' }
-        ]
-      },
-      {
-        text: 'Converter',
-        items: [
-          { text: 'Front Matter', link: '/converter/front-matter-converter' },
-          { text: 'JSON', link: '/converter/json-converter' },
-          { text: 'YAML', link: '/converter/yaml-converter' }
-        ]
-      },
-      {
-        text: 'Reference',
-        items: [
-          { text: 'File', link: '/ref/file' },
-          { text: 'Directory', link: '/ref/directory' },
-          { text: 'List', link: '/ref/list'},
-          { text: 'Editor', link: '/ref/editor' }
-        ]
-      }
-    ],
+	title: "loom-io",
+	description: "weave your data access",
+	lastUpdated: true,
+	themeConfig: {
+		logo: "/loom-io.png",
+		// https://vitepress.dev/reference/default-theme-config
+		nav: [
+			{ text: "Home", link: "/" },
+			{ text: "Docs", link: "/core/intro" },
+		],
+		sidebar: [
+			{
+				text: "Getting Started",
+				items: [
+					{ text: "Introduction", link: "/core/intro" },
+					{ text: "Setup", link: "/core/setup" },
+					{ text: "Examples", link: "/core/examples" },
+				],
+			},
+			{
+				text: "Source Adapter",
+				items: [
+					{ text: "In-Memory", link: "/adapter/in-memory-adapter" },
+					{ text: "Filesystem", link: "/adapter/node-filesystem-adapter" },
+					{ text: "S3-Minio", link: "/adapter/minio-s3-adapter" },
+				],
+			},
+			{
+				text: "Converter",
+				items: [
+					{ text: "Combined", link: "/converter/combined-converter" },
+					{ text: "Front Matter", link: "/converter/front-matter-converter" },
+					{ text: "JSON", link: "/converter/json-converter" },
+					{ text: "YAML", link: "/converter/yaml-converter" },
+				],
+			},
+			{
+				text: "Reference",
+				items: [
+					{ text: "File", link: "/ref/file" },
+					{ text: "Directory", link: "/ref/directory" },
+					{ text: "List", link: "/ref/list" },
+					{ text: "Editor", link: "/ref/editor" },
+				],
+			},
+		],
 
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/cotton-coding/loom-io' }
-    ]
-  }
-})
+		socialLinks: [
+			{ icon: "github", link: "https://github.com/cotton-coding/loom-io" },
+		],
+	},
+});

documentation/converter/combined-converter.md

@@ -0,0 +1,51 @@
+# Combining Converters
+
+Sometimes files content could be written in different formats like `json` and `yaml`, but the information is the same, so you will note care about the format and just have a json like object. `CombinedConverter`is doing this task for you. Combined with a LoomFile it directly reads the data from the file and convert it to `json`if one of the registered converter can handle the file type.
+
+::: code-group
+
+```sh [npm]
+npm add @loom-io/converter
+```
+
+```sh [pnpm]
+pnpm add @loom-io/converter
+```
+
+```sh [bun]
+bun add @loom-io/converter
+```
+
+:::
+
+## Usage
+
+At least it works still as all other converter, but you need to register other converter to do the convert task.
+
+```ts
+import { createCombinedConverter, NoValidFileConverterException  } from '@loom-io/converter';
+import { createJsonConverter } from '@loom-io/json-converter';
+import { createYamlConverter } from '@loom-io/yaml-converter';
+import { MemoryAdapter } from '@loom-io/memory-adapter';
+
+const adapter = new MemoryAdapter();
+const converter = createCombinedConverter([createJsonConverter(), createYamlConverter()], {
+	failOnNoConverter: true // this is the default value.
+})
+
+const file = adapter.file('some/random/file.yaml')
+
+try {
+	const json = await converter.parse(file);
+	// do some stuff with the data ....
+} catch ( error ) {
+	if(error instanceOf NoValidFileConverterException){
+		console.log('do something');
+	}
+	throw error;
+}
+```
+
+## Build a compatible converter
+
+Converters have a very simple base structure, to be compatible they just need to full fill the `FileConverter` interface. Take a look a the code of the [json](https://github.com/cotton-coding/loom-io/blob/main/plugins/json-converter/src/json-converter.ts) or [yaml](https://github.com/cotton-coding/loom-io/blob/main/plugins/yaml-converter/src/yaml-converter.ts) converter to see some easy implementations.

documentation/converter/front-matter-converter.md

@@ -5,7 +5,7 @@ description: This converter allows you to read files such as markdown files with
 
 # Front Matter Converter
 
-Add this converter to read files with a front matter part as json.
+Use this converter to read files with a front matter part as json.
 
 ::: code-group
 
@@ -25,33 +25,36 @@ bun add @loom-io/front-matter-converter
 
 ## Usage
 
-When reading, the converter returns a file with the attributes `data` and `content`. The first is the json converted header part. The second is a string containing the content.
-
-But before using it, you need to register the yaml converter
+When reading, the converter returns a file with the attributes `data` and `content`. The first is the json converted header part. The second is a string containing the content. The content will not be converted by default. By default the converter only reads markdown files (md), but any other file type could be read as well. Setting the option will overwrite the default value.
 
 ```ts
-import Loom from "@loom-io/core";
-import matterConverter from "@loom-io/front-matter-converter";
+import { createFrontMatterConverter } from "@loom-io/front-matter-converter";
 
-Loom.register(matterConverter());
-// Other file types
-Loom.register(matterConverter({ extensions: ["md", "nyk"] }));
-```
+// at default it reads markdown files (md)
+const matterConverter = createFrontMatterConverter();
+// but every other file type could be set as well
+const nykMatterConverter = createFrontMatterConverter({
+	extensions: ["nyk"]
+})
 
-As seen in the example above, you can specify which file extension it should try to convert. If no value is given, it will only react to markdown files. This will be overwritten by the given value.
-If there is no front matter part, `data` will be undefined and if there is no content, `content` will be an empty string. When writing the stringify will analyse the given function and convert it to a file. If the given value has more than just a `data` or `content` key it will only be translated to a header. You can also set only one of the two keys.
+```
+If there is no front matter part, `data` will be undefined and if there is no content, `content` will be an empty string. When writing the unify function will analyse the given function and convert it to a file. If the given value has more than just a `data` or `content` key it will only be translated to a header. You can also set only one of the two keys.
 
 ```ts
-const mdFile = await Loom.file("memory://some/yaml/file.md");
-const fileData = await mdFile.json();
+const adapter = new MemoryAdapter();
+const mdFile = adapter.file("some/yaml/file.md");
+const converter = createFrontMatterConverter();
+const fileData = await converter.parse(mdFile);
 fileData.data.someValue = "test";
 fileData.content = `
 #Headline
 
 some random markdown
 
 `;
-mdFile.stringify(data);
+
+converter.unify(mdFile, fileData);
+
 ```
 
 Be careful when writing. A `undefined` value for content or data will still overwrite the section!

documentation/converter/json-converter.md

@@ -25,20 +25,14 @@ bun add @loom-io/json-converter
 
 ## Usage
 
-Before using it you need to register the json converter
+Under the hood the json converter fits the standard `JSON.parse` and `JSON.stringify` and just reads the data from file as text. So the benefits are mainly existing in combination with the [CombinedConverter](/converter/combined-converter)
 
 ```ts
-import Loom from "@loom-io/core";
-import jsonConverter from "@loom-io/json-converter";
+import { createJsonConverter } from "@loom-io/json-converter";
 
-Loom.register(jsonConverter());
-```
-
-This allows you to read and write json files
-
-```ts
-const jsonFile = await Loom.file("memory://some/json/file.json");
-const data = await jsonFile.json();
+const jsonFile = adapter.file("some/yaml/file.json");
+const converter = createJsonConverter();
+const data = await converter.parse(jsonFile);
 data.val = "test";
-jsonFile.stringify(data);
+await converter.unify(jsonFile, data);
 ```

documentation/converter/yaml-converter.md

@@ -25,20 +25,14 @@ bun add @loom-io/yaml-converter
 
 ## Usage
 
-Before using, you need to register the yaml converter
+You can read and write yaml files with the suffixes `yaml` adn `yml`.
 
 ```ts
-import Loom from "@loom-io/core";
-import yamlConverter from "@loom-io/yaml-converter";
+import { createYamlConverter } from "@loom-io/yaml-converter";
 
-Loom.register(yamlConverter());
-```
-
-You can read and write yaml files with the suffixes `yaml` adn `yml`
-
-```ts
-const yamlFile = await Loom.file("memory://some/yaml/file.yaml");
-const data = await yamlFile.json();
+const yamlFile = adapter.file("some/yaml/file.yaml");
+const converter = createJsonConverter();
+const data = await converter.parse(yamlFile);
 data.val = "test";
-yamlFile.stringify(data);
-```
+await converter.unify(yamlFile, data);
+```

documentation/core/examples.md

@@ -14,12 +14,11 @@ Have a look at the specific reference to get all the details of the functionalit
 As show in the chapter before, do not forget to setup and config loom-io before usage.
 
 ```ts
-import Loom from "@loom-io/core";
-import fsAdapter from "@loom-io/node-filesystem-adapter";
+import FsAdapter from "@loom-io/node-filesystem-adapter";
 
-// Now we add the filesystem adapter.
+// Now we create a instance of the filesystem adapter.
 // By default the root of our filesystem is your project directory
-Loom.register(fsAdapter("file://"));
+const adapter = new FsAdapter();
 ```
 
 The following examples will not show registering an adapter every time, as you will probably only need to do this once.
@@ -100,17 +99,19 @@ It can be annoying to think about the file format all the time when reading. Whe
 import MemoryAdapter from "@loom-io/in-memory-adapter"
 import jsonConverter from '@loom-io/json-converter';
 import yamlConverter from '@loom-io/yaml-converter':
+import { createCombinedConverter } from '@loom-io/converter'
+
+
+const converter = createCombinedConverter([jsonConverter(), yamlConverter()])
 
-Loom.register(jsonConverter());
-Loom.register(yamlConverter());
 
 const adapter = new MemoryAdapter()
 
 const filePaths = ['file://test.yml', 'file://test.json'];
 
 for(let filePath of filePaths) {
   const file = adapter.file(filePath);
-  console.log(await file.json());
+  console.log(await converter.parse(file));
 }
 
 ```