docs: add v1.1.0-next.10 documentation

README.md

@@ -15,7 +15,9 @@
 ![MIT License][license-badge]
 ![semantic-release][semantic-badge]
 
-Configuration management
+## Config <!-- omit in toc -->
+
+a type-safe, simple yet powerful library for defining and accessing configuration.
 
 </div>
 
@@ -42,7 +44,7 @@ $ npm install --save-dev @fullstacksjs/config
 ### Deno
 
 ```typescript
-import * as config from 'https://raw.githubusercontent.com/fullstacksjs/config/main/mod.ts'
+import { Config } from 'https://raw.githubusercontent.com/fullstacksjs/config/main/mod.ts'
 ```
 
 ### Browser

docs/package.json

@@ -10,24 +10,24 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "@fullstacksjs/toolbox": "4.6.1",
-    "@types/node": "20.8.9",
-    "@types/react": "18.2.33",
-    "@types/react-dom": "18.2.14",
+    "@fullstacksjs/toolbox": "^4.7.0",
+    "@types/node": "^20.10.5",
+    "@types/react": "^18.2.45",
+    "@types/react-dom": "^18.2.18",
     "autoprefixer": "10.4.16",
-    "eslint": "8.52.0",
-    "eslint-config-next": "14.0.0",
-    "next": "14.0.0",
+    "eslint": "^8.56.0",
+    "eslint-config-next": "^14.0.4",
+    "next": "^14.0.4",
     "nextra": "^2.13.2",
     "nextra-theme-docs": "^2.13.2",
-    "postcss": "8.4.31",
+    "postcss": "^8.4.32",
     "react": "18.2.0",
     "react-dom": "18.2.0",
-    "tailwindcss": "3.3.5",
-    "typescript": "5.2.2"
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.3.3"
   },
   "volta": {
-    "node": "18.16.0",
-    "npm": "9.6.7"
+    "node": "20.10.0",
+    "npm": "10.2.5"
   }
 }

docs/pages/_meta.json

@@ -1,4 +1,6 @@
 {
   "index": "Introduction",
-  "getting-started": "Getting Started"
+  "getting-started": "Getting Started",
+  "config": "Config",
+  "schema": "Schema"
 }

docs/pages/config.mdx

@@ -0,0 +1,58 @@
+# Config
+
+## Constructor
+
+Creates a new configuration instance based on the provided schema.
+
+#### Parameters
+
+`schema`: A schema object that defines the configuration schema using the provided methods.
+
+#### Example
+
+```ts
+const config = new Config({
+  port: Config.string(),
+  nested: Config.object({
+    foo: Config.string(),
+  }),
+})
+```
+
+## parse
+
+Parses and validate the configuration against the schema.
+
+#### Parameters
+
+`config`: An object containing the configuration values to be parsed.
+
+#### Example
+
+```typescript
+config.parse({ port: 3000, nested: { foo: 'bar' } })
+```
+
+## get
+Retrieves the value of a specific configuration key.
+
+#### Parameters
+
+`path`: The configuration key to retrieve.
+
+#### Example
+
+```typescript
+config.get('port') // 3000
+config.get('nested.foo') // bar
+```
+
+## getAll
+
+Returns an object containing all configuration values.
+
+#### Example
+
+```typescript
+config.getAll('port') // { port: 3000, nested: { foo: 'bar' } }
+```

docs/pages/index.mdx

@@ -1,14 +1,20 @@
 # Introduction
 
 <div className="flex justify-center my-20">
-  <img className="w-full" src="thumbnail.png" />
+  <img className="w-full" src="banner.png" />
 </div>
 
-Config!
+A **zero-dependency** 📦, **type-safe** 🚧, simple yet powerful library
+for defining and accessing configuration.
 
-## Motivation
+## Why Config?
 
-TBD
+- 📦️ **Zero-dependencies**: Fully-tested standalone solution, zero maintenance cost.
+- 🛟 **Fail Fast**: Application starts only if configurations are correct, ensuring high reliability.
+- 🎛 **Type-safety**: Runtime schema parsing allows for complete TypeScript type inference.
+- 🏗️ **Modern**: Compatible with ESM, Deno, NodeJS, Bun, and browsers.
+- 🧪 **Fully tested**: Comprehensive unit tests cover all functionalities, ensuring robustness.
+- 🔌 **Technlogy-Agnostic**: Not Coupled to any Runtime or Framework.
 
 ## Usage
 

docs/pages/schema.mdx

@@ -0,0 +1,81 @@
+# Schema
+
+The schema is the core structure used to define the shape and rules of the configuration.
+
+## Basic Usage
+
+```typescript
+import { Config } from '@fullstacksjs/config';
+
+const mySchema = {
+  number: Config.number(),
+  string: Config.string(),
+  boolean: Config.boolean(),
+  array: Config.array(Config.string()),
+  object: Config.object({
+    key: Config.string(),
+  }),
+};
+```
+
+## Schema Options
+
+Base option for schema definition.
+
+### Type Definition
+
+```typescript
+type SchemaOptions<T> = {
+  coerce: boolean
+  default: T
+}
+```
+
+### Options
+
+#### coerce
+
+Controls runtime type coercion. when enabled parser tries to coerce the provided value. (default: `true`)
+
+##### Example
+
+```typescript
+const config = new Config({
+  port: Config.number({ coerce: true }),
+});
+config.parse({ port: '3000' })
+config.get(port) // 3000
+typeof config.get(port) // "number"
+```
+
+```typescript
+const config = new Config({
+  port: Config.number({ coerce: false }),
+});
+config.parse({ port: '3000' }) // Invalid configuration: The "port" expected to be "number" but a "string" was provided
+```
+
+#### default
+
+Defines the default value when the value is `null` or `undefined`.
+
+```typescript
+const config = new Config({
+  port: Config.number({ default: 3000 }),
+});
+config.parse({})
+config.get(port) // 3000
+
+config.parse({ port: undefined })
+config.get(port) // 3000
+
+config.parse({ port: null })
+config.get(port) // 3000
+```
+
+## Schemas
+
+import meta from './schema/_meta.json';
+import { TOC } from '../components/TOC.tsx';
+
+<TOC base="/schema" meta={meta} />

docs/pages/schema/_meta.json

@@ -0,0 +1,7 @@
+{
+  "array": "Array",
+  "boolean": "Boolean",
+  "number": "Number",
+  "string": "String",
+  "object": "Object"
+}

docs/pages/schema/array.mdx

@@ -0,0 +1,22 @@
+# Array
+
+Defines an array schema.
+
+## Parameters
+
+`schema`: [Schema](/schema)
+
+### Example
+
+```typescript
+const arraySchema = Config.array(Config.string()); // stirng[]
+```
+
+> **Caution**:
+> Inner schema is alwayas `required`!\
+> **Caution**:
+> Inner schema coercion is `false` by default!
+
+## Coercion
+
+Coercion is disabled for array.

docs/pages/schema/boolean.mdx

@@ -0,0 +1,39 @@
+# Boolean
+
+Defines a boolean schema.
+
+## Parameters
+
+`options`: [Schema Options](./schema#schema-options)
+
+### Example
+
+```typescript
+const booleanSchema = Config.boolean(schemaOptions);
+```
+
+## Methods
+
+### required
+
+Mark schema as required.
+
+```typescript
+const config = new Config({
+  password: Config.boolean().required(),
+});
+
+config.parse({ password: undefined }) // Invalid configuration: The "password" is required but the given value is "undefined"
+```
+
+## Coercion
+When the value is string, it coerces `'0'` or `'false'` to false (case-insensitve), otherwise to passes it to the `Boolean` function.
+
+```ts
+const coercion = value => {
+  const falseRegex = /(false|0)/i;
+  return typeof value === 'string'
+    ? !falseRegex.test(value)
+    : Boolean(value);
+}
+```

docs/pages/schema/number.mdx

@@ -0,0 +1,56 @@
+# Number
+
+Defines a number schema.
+
+## Parameters
+
+`options`: [Schema Options](./schema#schema-options)
+
+### Example
+
+```typescript
+const numberSchema = Config.number(schemaOptions);
+```
+
+## Methods
+
+### min
+
+Defines minimum valid value (inclusive).
+
+```typescript
+const config = new Config({
+  age: Config.number().min(18),
+});
+config.parse({ age: 10 }) // Invalid configuration: The "age" expected to be more than or equal to "18" but "10" was provided',
+```
+
+### min
+
+Defines maximum valid value (inclusive).
+
+```typescript
+const config = new Config({
+  age: Config.number().max(20),
+});
+config.parse({ age: 22 }) // Invalid configuration: The "age" expected to be less than or equal to "20" but "22" was provided',
+```
+
+### required
+
+Mark schema as required.
+
+```typescript
+const config = new Config({
+  password: Config.number().required(),
+});
+
+config.parse({ password: undefined }) // Invalid configuration: The "password" is required but the given value is "undefined"
+```
+
+
+## Coercion
+
+```ts
+const coercion = value => Number(value)
+```

docs/pages/schema/object.mdx

@@ -0,0 +1,35 @@
+# Object
+
+Defines an object schema.
+
+## Parameters
+
+schema: Record\<string, [Schema](./schema)>
+
+### Example
+
+```typescript
+const objectSchema = Config.object({
+  foo: Config.string(),
+  nested: Config.object({
+    bar: Config.boolean().required(),
+  }),
+});
+
+/*
+{
+  foo: string | undefined,
+  nested: {
+    bar: boolean;
+  }
+}
+*/
+```
+
+> **Caution**:
+> Inner schema coercion is `false` by default!
+
+
+## Coercion
+
+Coercion is disabled for object.