Documentation

.github/workflows/deploy-docs.yml

@@ -0,0 +1,63 @@
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+#
+name: Deploy loom-io to Github Pages
+
+on:
+  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+  # using the `master` branch as the default branch.
+  push:
+    branches: [main]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      - uses: pnpm/action-setup@v3
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: pnpm insatll
+      - name: Build with VitePress
+        run: pnpm run -r docs:build --if-present
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: documentation/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -180,3 +180,5 @@ dist
 tests/integration/test-tmp/
 
 test-tmp/
+
+documentation/.vitepress/cache/

adapters/minio/src/exports/lib.ts

@@ -1,17 +1,12 @@
 import { source, type S3Options } from '../core/source';
 import { type Directory, PLUGIN_TYPE, type LoomSourceAdapter, LoomFile, MaybePromise } from '@loom-io/core';
 
-export type S3MinioAdapterOptions = S3Options & {
-	bucket: string;
-};
-
-export default (key: string = 's3://', options: S3MinioAdapterOptions): LoomSourceAdapter => ({
+export default (key: string = 's3://', bucket: string, s3config: S3Options): LoomSourceAdapter => ({
 	$type: PLUGIN_TYPE.SOURCE_ADAPTER,
 	source: (link: string, Type?: typeof Directory | typeof LoomFile): MaybePromise<Directory | LoomFile> | void => {
 		if(link.startsWith(key)) {
 			const path = link.slice(key.length);
-			const { bucket, ...s3options } = options;
-			return source(path, bucket, s3options, Type);
+			return source(path, bucket, s3config, Type);
 		}
 	}
 });

adapters/minio/test/source.spec.ts

@@ -10,7 +10,4 @@ const s3config = {
 };
 
 
-testSource('s3://', S3MinioSourceAdapter(undefined, {
-	bucket: 'test-bucket',
-	...s3config
-}));
+testSource('s3://', S3MinioSourceAdapter(undefined, 'test-bucket', s3config));

documentation/.vitepress/config.mts

@@ -0,0 +1,54 @@
+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: 'Doc', 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: 'JSON', link: '/converter/markdown-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' }
+    ]
+  }
+})

documentation/adapter/in-memory-adapter.md

@@ -0,0 +1,34 @@
+---
+---
+
+# In Memory Adapter
+
+This adapter was manly created for testing, but could also be used as a replacement for any other adapter. As the name told it stores all data in memory, which make it probably the fastest adapter.
+
+::: code-group
+
+```sh [npm]
+npm add @loom-io/in-memory-adapter
+```
+
+```sh [pnpm]
+pnpm add @loom-io/in-memory-adapter
+```
+
+```sh [bun]
+bun add @loom-io/in-memory-adapter
+```
+
+:::
+
+## Setup and Config
+
+The adapter only has an default export and export a function to configure the adapter. In this case the only option is to set the key to reference it. As with all other adapters you can register it with different identifiers. The default identifier is `memory://`.
+
+```ts
+import Loom from "@loom-io/core";
+import memoryAdapter from "@loom-io/in-memory-adapter";
+
+Loom.register(memoryAdapter("my-memory://"));
+Loom.register(memoryAdapter());
+```

documentation/adapter/minio-s3-adapter.md

@@ -0,0 +1,50 @@
+---
+---
+
+# S3 Adapter
+
+Connects your S3 as it is a filesystem storage and based on the minio library. Even if it based on the minio library you can use it with all other S3 Storage e.g.: Digital Ocean Spaces, Amazon S3
+
+::: code-group
+
+```sh [npm]
+npm add @loom-io/minio-s3-adapter
+```
+
+```sh [pnpm]
+pnpm add @loom-io/minio-s3-adapter
+```
+
+```sh [bun]
+bun add @loom-io/minio-s3-adapter
+```
+
+:::
+
+## Setup and config
+
+Mainly the configuration is the same as with [minio](https://min.io/docs/minio/linux/developers/javascript/API.html). You just have setup a bucket name in advance. The default key to identify is `s3://`
+
+```ts
+import Loom from "@loom-io/core";
+import s3Adapter from "@loom-io/s3-minio-adapter";
+
+const s3ConfigMinio = {
+	endPoint: "play.min.io",
+	port: 9000,
+	useSSL: true,
+	accessKey: "Q3AM3UQ867SPQQA43P2F",
+	secretKey: "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG",
+};
+
+const s3ConfigDigitalOcean = {
+	endpoint: "ams3.digitaloceanspaces.com",
+	accessKey: "key",
+	secretKey: "secret",
+};
+
+// Set own key, bucket name and config for minio
+Loom.register(memoryAdapter("my-s3://", "my-bucket", s3ConfigMinio));
+// set default key (s3://), bucket name and digital ocean space config
+Loom.register(memoryAdapter(undefined, "other-bucket", s3ConfigDigitalOcean));
+```

documentation/adapter/node-filesystem-adapter.md

@@ -0,0 +1,36 @@
+---
+---
+
+# Filesystem Adapter
+
+Access Files from you local filesystem. Don't be confused from the node in the package name, it should also work with bun, because it is node compatible, but there are plans to do a more Bun specific adapter. For now you should also use this for bun, because all adapter exchange able you can easily switch later to the Bun specific adapter if you want to.
+
+::: code-group
+
+```sh [npm]
+npm add @loom-io/node-filesystem-adapter
+```
+
+```sh [pnpm]
+pnpm add @loom-io/node-filesystem-adapter
+```
+
+```sh [bun]
+bun add @loom-io/node-filesystem-adapter
+```
+
+:::
+
+## Setup and config
+
+The default key for this adapter is `file://`, by default the adapter sets your project directory as root directory (manly the directory you starts you server from), but you can set any other directory. This directory looks like and is accessed like you root directory, so you will not be able to break out of this directory.
+
+```ts
+import Loom from "@loom-io/core";
+import filesystemAdapter from "@loom-io/node-filesystem-adapter";
+
+// sets key to root:// and the root path to you filesystem root, be careful
+Loom.register(filesystemAdapter("root://", "/"));
+// use default config. Key is file:// and the "root"-Directory is your project root
+Loom.register(filesystemAdapter());
+```

documentation/core/examples.md

@@ -0,0 +1,84 @@
+# Examples
+
+loom-io simplify the access to different storing systems and brings you additional functionality like reading directories recursive, search files, read them line by line or auto convert files to json.
+
+Take a look at the specific reference to get all details of functionality. This chapter will describe the api by use cases, but will not show the full functionality.
+
+## Configure
+
+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";
+
+// We add the adapter for filesystem now.
+// By default the root of our filesystem is your project directory
+Loom.register(fsAdapter("file://"));
+```
+
+The following examples will not show a registration of a adapter every time, because you will probably do this only once.
+
+## Create a directory and a file
+
+Creating a directory or file object do not mean the directory or file does exists. This means you could firstly create a virtual object and than create the real object in the storage system
+
+```ts
+import Loom from "@loom-io/core";
+
+const dir = await Loom.dir("file://welcome");
+const file = dir.file("hello-world.md");
+// till here everything is virtual and do not have to exit on your filesystem;
+
+console.log(await file.exists()); // Will be false;
+console.log(await dir.exists()); // Will be false;
+
+// create an empty file welcome/hello-world.md
+await file.create();
+
+console.log(await dir.exists()); // Will be true;
+console.log(await file.exists()); // Will be false;
+```
+
+While creating the file the directory was directly created too. To avoid and automatic creation of the directory use `file.write`
+
+## List all files in a directory
+
+This is one of the first functions implemented in the library and one of the main reason. We already registered an adapter above so it will be not necessary to have a second one, but to have a full example we will do it anyways. To get all details about the adapter or dir take a look to the doc sections
+
+```ts
+import Loom from "@loom-io/core";
+
+// the directory do not have to exist
+//select the root dir, in this case the project dir
+const dir = await Loom.dir("file://");
+//read dir recursive and search for files
+const files = await dir.files(true);
+
+for (let file of files) {
+	console.log(file.path);
+}
+```
+
+## List content of a Directory
+
+```ts
+import Loom, { isFile, isDirectory } from "@loom-io/core";
+
+const dir = await Loom.dir("file://");
+const list = await dir.list() // returns a iterable to get Files and Directories
+
+for(let el of list) {
+  if( isFile(el) ) { // check if it is a File
+    console.log(await el.text()); // do some Stuff with the file content
+  } else ( isDirectory(el) ) { // just to show, it could only be a file or directory
+    console.log((await el.list()).length)
+  }
+}
+
+// to get the parent of a directory
+if(dir.parent !== undefined) {
+  await dir.parent.list()
+}
+
+```

documentation/core/intro.md

@@ -0,0 +1,16 @@
+---
+---
+
+# Introduction
+
+Nowadays there a lots of possible to store data, most application use sql like databases to handle there data. Loom-IO wants to go one step back, to classic files and also a lot of site generators go back to human readable files. At least there a still different formats and possibilities to store data: Git, Filesystem, S3, to just name some of them.
+
+To make this simpler and more easily, this lib abstract this and offers different adapters for storing systems and file formats. It even give you the possibility to create your own ones to be 100% flexible.
+
+## Modules
+
+To solve this problem the lib is split in multiple parts, what seem to be more complex at the first view. To make this easier for you, there are some pre bundled modules. You will find them in the base section.
+
+## Less dependencies
+
+Loom-IO will be build with the philosophy to avoid dependencies to other libraries, to reduce your risk of unknown dependencies. At least we wouldn't reinvent the wheel and implement everything at our own, so for example the YAML-Adapter is based on a other parsing library, but at least it is your decision to use it, implement your own or just a other one based on a other library.