Feature/82 storage location rework

docs/db/FindOptions.md

@@ -107,8 +107,9 @@ Results can be ordered and sorted by any property inside the **Document** in asc
 import { Flotsam } from 'flotsam/db';
 import { Like } from 'flotsam/evaluators';
 
-const db = new Flotsam({ root: '.store' });
-await db.connect();
+const db = new Flotsam();
+
+await db.connect('flotsam');
 
 const collection = await db.collect<{ value: string }>('collection');
 
@@ -130,8 +131,9 @@ To enable pagination, results can be `skipped` and `taken`.
 import { Flotsam } from 'flotsam/db';
 import { Like } from 'flotsam/evaluators';
 
-const db = new Flotsam({ root: '.store' });
-await db.connect();
+const db = new Flotsam();
+
+await db.connect('flotsam');
 
 const collection = await db.collect<{ value: string }>('collection');
 
@@ -151,8 +153,9 @@ The query can have a limit passed, which will limit the number of results to ope
 import { Flotsam } from 'flotsam/db';
 import { Like } from 'flotsam/evaluators';
 
-const db = new Flotsam({ root: '.store' });
-await db.connect();
+const db = new Flotsam();
+
+await db.connect('flotsam');
 
 const collection = await db.collect<{ value: string }>('collection');
 

docs/db/Flotsam.md

@@ -6,43 +6,91 @@ The `Flotsam` class is the main interface for using the database. All operations
 
 ## Configuration
 
-A configuration object can be used to configure the **Fløtsam** instance.
+A optional configuration object can be used to configure the **Fløtsam** instance by passing it to it's constructor.
+
+### Configuration Properties - Storage
 
 ```ts
 import { Flotsam } from 'flotsam/db';
 
 const db = new Flotsam({
-    root: '.store', // Directory to store the created JSON Documents.
-    log: '.log', // File to store error and query logs.
-    quiet: false, // Boolean indicating if logs should be suppressed.
-    auth: 'secretKey', // Encryption key for encrypting the stored Document.
-});
+    //... other config options
+    storage: {
+        useProjectStorage: true //  use the cwd of the project as storage root
+        dir: './.storage' // use a dedicated .storage directory to create the database instances
+    }
+})
 ```
 
-### Configuration Properties
+#### `useProjectStorage`
+
+Type: `boolean` | `undefined`
+
+Boolean indicating if the storage directory should be created from the projects root / `cwd` or from the operating systems main storage directory.
 
-#### `Root`
+#### `dir`
 
-Type: `string`
+Type: `string` | `undefined`
 
-String describing the root of the directory used to store the JSON documents.
+Optional string used as path between the storage root, which is either the projects `cwd` or the operating systems main storage directory, and the database name as directory.
+
+### Configuration Properties - Log
+
+```ts
+import { Flotsam } from 'flotsam/db';
+
+const db = new Flotsam({
+    //... other config options
+    log: {
+        path: './logs/log.file', // the log file will be named log.file and be stored in the 'logs' directory
+        quiet: false, // do not suppress logs
+        maxSafeFileSize: 157286400, // set a maximum filesize in byte
+    },
+});
+```
 
-#### `log`
+#### `path`
 
-Type: `string | undefined`
+Type: `string` | `undefined`
 
-If a string is passed as property, the string will be used as location for a log file, where all errors are logged to.
-The logfile will be created relative to the storage root of the db.
+If a string is used as property, the string will be used as location for a log file, where all errors are logged to.
+The logfile will be created relative to the project's root. If the property is undefined, no log file is created.
 
 #### `quiet`
 
-Type: `boolean | undefined`
+Type: `boolean` | `undefined`
 
 Boolean indicating if logs & warnings should be suppressed.
 
-#### `auth`
+#### `maxSafeFileSize`
+
+Type: `number` | `undefined`
+
+Optional number indicating the maximum size of the log file in bytes before it's being truncated. If 0 is passed, the log file will never be truncated.
+
+### Configuration Properties - Auth
+
+```ts
+import { Flotsam } from 'flotsam/db';
+
+const init = {
+    //... other config options
+    auth: {
+        useEncryption: true,
+        key: 'secretKey',
+    },
+};
+```
+
+#### `useEncryption`
+
+Type: `boolean` | `undefined
+
+Boolean indicating if encryption should be used.
+
+#### `key`
 
-Type: `string | undefined
+Type: `string` | `undefined
 
 A string used as secret to encrypt the JSON Documents on disk. If no string is passed,
 no encryption will take place.`
@@ -63,9 +111,9 @@ Closes the connection of the **Flotsam** instance and serializes all Documents t
 await db.close();
 ```
 
-#### `flotsam.connect(callback: Callback | null, error?: ErrorHandler): Promise<boolean>`
+#### `flotsam.connect(connectionSettings: ConnectionSettings | string, callback: Callback | null, error?: ErrorHandler): Promise<boolean>`
 
-Connects the **Flotsam** instance. The underlying storage space is validated or created in this step. A success and error Callback can be passed to method, which will be called when the connection succeeds or fails.
+Connects the **Flotsam** instance. The underlying storage space is validated or created in this step. A connection settings object or a database name string is required. A success and error Callback can be passed to method, which will be called when the connection succeeds or fails.
 
 ```ts
 import { Flotsam } from 'flotsam/db';

docs/db/RecordLinks.md

@@ -40,9 +40,9 @@ import { Flotsam, Link } from 'flotsam/db';
 import { Contains } from 'flotsam/evaluators';
 import { NotNull, IsString, IsInt, RecordFrom, CollectionOf } from 'flotsam/validators';
 
-const db = new Flotsam({ root: './tests/.store', quiet: true });
+const db = new Flotsam();
 
-await db.connect();
+await db.connect('flotsam');
 
 // Create the models used for the Collections.
 

docs/examples/express.md

@@ -60,10 +60,8 @@ import express from 'express';
 const app = express();
 
 + // create the database
-+ const db = new Flotsam({
-+     root: '.store'
-+ })
-+ await db.connect()
++ const db = new Flotsam()
++ await db.connect('flotsam')
 
 // add the json body parser middleware
 app.use(express.json());
@@ -124,10 +122,8 @@ import { Flotsam } from 'flotsam/db';
 const app = express();
 
 // create the database
-const db = new Flotsam({
-    root: '.store',
-});
-await db.connect();
+const db = new Flotsam();
+await db.connect('flotsam');
 
 // add the json body parser middleware
 app.use(express.json());

docs/examples/ts-node.md

@@ -44,21 +44,17 @@ Open the `main.ts` file you created and add the following lines to import and cr
 ```ts
 + import { Flotsam } from 'flotsamjs/db';
 
-+ const db = new Flotsam({
-+     root: '.store',
-+ });
-+ await db.connect();
++ const db = new Flotsam();
++ await db.connect('flotsam');
 ```
 
 Create a `Collection`.
 
 ```ts
 import { Flotsam } from 'flotsamjs/db';
 
-const db = new Flotsam({
-    root: '.store',
-});
-await db.connect();
+const db = new Flotsam();
+await db.connect('flotsam');
 
 // create a Collection.
 // this will also create a equally named directory in the
@@ -154,10 +150,8 @@ In case you want to remove a collection completely, you can `jettison` it.
 ```ts
 import { Flotsam } from 'flotsamjs/db';
 
-const db = new Flotsam({
-    root: '.store',
-});
-await db.connect();
+const db = new Flotsam();
+await db.connect('flotsam');
 
 // create a Collection.
 // this will also create a equally named directory in the

readme.md

@@ -51,14 +51,12 @@ After importing the class, an instance is created that will represent the Databa
 ```ts
 import { Flotsam } from 'flotsam/db';
 
-// create the Fløtsam instance and configure it
-const db = new Flotsam({
-    root: '.store', // path to the directory to store the JSON Documents
-});
+// create the Fløtsam instance
+const db = new Flotsam();
 
-// connect to the Database instance. If the storage directory
+// connect to a Database instance. If the storage directory
 // does not yet exist, it will be created in this step.
-await db.connect();
+await db.connect('flotsam');
 ```
 
 ### Collections
@@ -68,8 +66,8 @@ A **Collection** is a subdivision of the Database instance, that holds a certain
 ```ts
 import { Flotsam } from 'flotsam/db';
 
-const db = new Flotsam({ root: '.store' });
-await db.connect();
+const db = new Flotsam();
+await db.connect('flotsam');
 
 // create the collection under a 'jetsam' namespace
 // this will create the physical directory, if it does not yet exist
@@ -83,8 +81,8 @@ const collection = await db.collect<{ description: string }>('jetsam');
 ```ts
 import { Flotsam } from 'flotsam/db';
 
-const db = new Flotsam({ root: '.store' });
-await db.connect();
+const db = new Flotsam();
+await db.connect('flotsam');
 
 // creating a custom schema to ensure type safety
 // during operations
@@ -121,8 +119,8 @@ While using **Find Options** is powerful, **Evaluators** make these Find Options
 import { Flotsam } from 'flotsam/db';
 import { Like, GreaterThan } from 'flotsam/evaluators';
 
-const db = new Flotsam({ root: '.store' });
-await db.connect();
+const db = new Flotsam();
+await db.connect('flotsam');
 
 type Jetsam = {
     description: string;
@@ -155,8 +153,8 @@ A **Collection** can receive a second optional argument to work as a **Schema Va
 import { Flotsam } from 'flotsam/db';
 import { NotNull, IsText, IsInt } from 'flotsam/validators';
 
-const db = new Flotsam({ root: '.store' });
-await db.connect();
+const db = new Flotsam();
+await db.connect('flotsam');
 
 type Jetsam = {
     description: string;

src/lib/Db/Collection.ts

@@ -101,7 +101,11 @@ export class Collection<T extends Record<PropertyKey, unknown>> {
     #observedQueries: Array<ObservedQuery<T>> = [];
     constructor(private ctx: Flotsam, private _namespace: string, private validationStrategy?: Validator<T>) {
         this.#dir = resolve(ctx.root, this._namespace);
-        this.#crypt = ctx.auth ? new Crypto(ctx.auth) : null;
+
+        if (ctx._auth && ctx._auth.useEncryption) {
+            const { key } = ctx._auth;
+            this.#crypt = new Crypto(key);
+        }
 
         process.on('SIGINT', async () => {
             await this.serialize();