External website for documentation (starting v2)

.github/workflows/release.yml

@@ -26,7 +26,7 @@ jobs:
 
     # remove tests in order to clean dependencies
     - name: Remove xxx_test.go files
-      run: rm -rf *_test.go docker-compose.yml examples/
+      run: rm -rf *_test.go docker-compose.yml examples/ docs/
 
     - name: Cleanup dependencies
       run: go mod tidy

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,35 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ npm install
+```
+
+### Local Development
+
+```
+$ npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ npm build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Deployed on Vercel.
+
+### Illustrations 🎨
+
+- https://github.com/egonelbre/gophers
+- https://github.com/MariaLetta/free-gophers-pack
+- https://github.com/ashleymcnamara/gophers

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/getting-started.md

@@ -0,0 +1,99 @@
+---
+title: 🚀 Getting started
+description: Let's discover samber/do in less than 5 minutes.
+sidebar_position: 1
+---
+
+# Getting started
+
+Let's discover **samber/do in less than 5 minutes**.
+
+## What you'll need
+
+Compatible with [Go](https://go.dev/doc/install/) 1.18 or more.
+
+This library has no dependencies except the Go std lib.
+
+Import package:
+
+```sh
+go get -u github.com/samber/do/v2
+```
+
+## Create a DI container
+
+The simplest way to start is to use the default options:
+
+```go
+import "github.com/samber/do/v2"
+
+injector := do.New()
+```
+
+## Service provider and invocation
+
+Services can be declared as a singleton or a factory. In this example, we will create 2 services `Car` and `Engine`, with a simple dependency relation.
+
+```go
+func main() {
+    // create DI container
+    i := do.New()
+
+    // inject both services into DI container
+    Provide[*Car](i, NewCar)
+    Provide[*Engine](i, NewEngine)
+
+    // invoking car will instantiate Car services and its Engine dependency
+    car, err := Invoke[*Car](i)
+    if err != nil {
+        log.Fatal(err.Error())
+    }
+
+    car.Start()  // that's all folk 🤗
+
+    // handle ctrl-c and shutdown services
+    i.ShutdownOnSignals(syscall.SIGTERM, os.Interrupt)
+}
+```
+
+Engine:
+
+```go
+type Engine struct {
+    Started bool
+}
+
+func (e *Engine) Shutdown() error {
+    // called on injector shutdown
+    e.Started = false
+    return nil
+}
+
+// Provider
+func NewEngine(i do.Injector) (*Engine, error) {
+    return &Engine{
+        Started: false,
+    }, nil
+}
+```
+
+Car:
+
+```go
+type Car struct {
+    Engine *Engine
+}
+
+func (c *Car) Start() {
+    c.Engine.Started = true
+    println("vroooom")
+}
+
+// Provider
+func NewCar(i do.Injector) (*Car, error) {
+    return &Car{
+        // import dependency
+        Engine: do.MustInvoke[*Engine](i),
+    }, nil
+}
+```

docs/docs/glossary.md

@@ -0,0 +1,74 @@
+---
+id: glossary
+title: 📚 Glossary
+description: Dependency injection glossary
+sidebar_position: 6
+---
+
+# Glossary
+
+## Dependency Injection (DI)
+
+A design pattern used in software development to achieve Inversion of Control (IoC) between classes and their dependencies. It's a technique for achieving loose coupling between objects and their collaborators, or dependencies.
+
+## Inversion of Control (IoC)
+
+A design principle where the flow of control is inverted compared to traditional procedural programming. Instead of the application-specific code controlling the execution of reusable code, the reusable code controls the execution. This principle is often implemented using techniques such as Dependency Injection, leading to more modular and easily maintainable code.
+
+## Injector
+
+In Dependency Injection (DI), an injector is a component that creates instances of classes and manages their dependencies. It's also known as the DI container or IoC (Inversion of Control) container.
+
+`do.Injector` is either a `*do.RootScope`, a `*do.Scope` or a `*do.VirtualScope`.
+
+## DI Container
+
+A DI Container is another term for the Injector in Dependency Injection. It's responsible for providing instances of classes and their dependencies.
+
+## Scope
+
+Kind of module. It contains many declaration singleton and service providers. It has access to the services from ancestors' scopes.
+
+## Root scope
+
+Top-level scope.
+
+## Virtual scope
+
+A chain of Service invocation will instantiate many VirtualScope, to track dependency cycles.
+
+## Child scope
+
+A scope that is nested within another scope. Variables defined in a child scope are only accessible within that scope and any nested scopes.
+
+## DAG
+
+Stands for Directed Acyclic Graph. It's a concept in mathematics and computer science. In the context of DI, it often refers to the graph of dependencies between different components or services.
+
+## Provider
+
+In DI, a provider is a component or a factory that creates instances of a service or a class.
+
+## Injection
+
+The process of providing a service to a scope. The injection can be done in different ways like provider injection or setter injection.
+
+## Invocation
+
+The process of executing a procedure or function through a call.
+
+## Lazy Service
+
+A service in DI that is not created until it is first requested.
+
+## Eager Service
+
+A service in DI that is created as soon as the application starts, not when it's first requested.
+
+## Transient Service
+
+A service in DI that is created anew each time it is requested.
+
+## Service Alias
+
+An alternative name given to a service in DI. It allows a service to be accessed using a different identifier.

docs/docs/scopes/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "📦 Injectors",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn how to split your services into multiple modules"
+  }
+}

docs/docs/scopes/clone.md

@@ -0,0 +1,38 @@
+---
+title: Clone
+description: Clone your global DI container
+sidebar_position: 3
+---
+
+# Clone
+
+Clone has the same service registrations as its parent, but it doesn't share the invoked service state.
+
+Cloning an injector can be very useful for test purposes.
+
+```go
+injector := do.New()
+
+Provide[*Car](i, NewCar)
+Provide[*Engine](i, NewEngine)
+
+// reset scope
+injector = injector.Clone()
+```
+
+## Clone with options
+
+```go
+injector := do.New()
+
+Provide[*Car](i, NewCar)
+Provide[Engine](i, NewEngine)
+
+// clone
+injector = injector.Clone()
+
+// replace Engine by *MockEngine
+do.Override[Engine](injector, func (i do.Injector) (Engine, error) {
+    return &MockEngine{}, nil
+})
+```

docs/docs/scopes/options.md

@@ -0,0 +1,56 @@
+---
+title: Injector options
+description: Injector options
+sidebar_position: 2
+---
+
+# Injector
+
+## Default options
+
+The simplest way to start is to use the default parameters:
+
+```go
+import "github.com/samber/do/v2"
+
+injector := do.New()
+```
+
+## Global container
+
+For a quick start, you may use the default global container. This is highly discouraged in production.
+
+```go
+import "github.com/samber/do/v2"
+
+Provide(nil, ...)
+Invoke(nil, ...)
+
+// equal to:
+
+Provide(do.DefaultRootScope, ...)
+Invoke(do.DefaultRootScope, ...)
+```
+
+## Custom options
+
+```go
+import "github.com/samber/do/v2"
+
+injector := do.NewWithOps(&do.InjectorOpts{
+    HookAfterRegistration func(scope *do.Scope, serviceName string) {
+        // ...
+    },
+    HookAfterShutdown     func(scope *do.Scope, serviceName string) {
+        // ...
+    },
+
+    Logf func(format string, args ...any) {
+        // ...
+    },
+
+    HealthCheckParallelism:   100,
+    HealthCheckGlobalTimeout: 1 * time.Second,
+    HealthCheckTimeout:       100 * time.Millisecond,
+})
+```