gs

func As ¶ added in v1.2.0

func As[T any]() reflect.Type

As returns the reflect.Type of the given generic interface type T. It is typically used with [BeanDefinition.Export] to register interfaces that a bean implements, allowing dependency injection by interface type.

Example:

type Service interface {
    Serve() error
}

type ServiceImpl struct{}

func (s *ServiceImpl) Serve() error { return nil }

gs.Provide(&ServiceImpl{}).Export(gs.As[Service]())

func Banner ¶

func Banner(banner string)

Banner sets a custom app banner.

func BindArg ¶ added in v1.2.0

func BindArg(fn any, args ...Arg) *gs_arg.BindArg

BindArg creates an argument whose value is computed dynamically by a function. It executes the function at bean creation time to get the actual argument value, and supports attaching conditions that control whether the argument is accepted.

Use cases:

• Conditional bean creation based on runtime state
• Complex initialization logic that requires multiple dependencies
• Lazy evaluation of expensive resources

Example:

gs.Provide(
    func(logger *Logger) *Service { ... },
    gs.BindArg(func() (*Logger, error) {
        return createLogger()
    }).Condition(gs.OnProperty("logging.enabled"))
)

func Group ¶ added in v1.2.3

func Group[T any, R any](tag string, fn func(c T) (R, error), d func(R) error)

Group reads a map from the specified configuration property, then iterates over each entry and creates one bean per entry using the constructor fn. The map key becomes the bean name, and the map value is passed to fn as the configuration for constructing the bean. An optional destructor d can be provided for cleanup when the application shuts down.

Use cases:

• Multiple database connections from configuration
• Multiple dynamic service clients configured in YAML
• Plugin architectures with configurable components

Example:

// Register multiple HTTP clients from configuration
gs.Group(
    "${http.clients}",
    func(cfg HTTPClientConfig) (*HTTPClient, error) {
        return NewHTTPClient(cfg)
    },
    func(c *HTTPClient) error {
        return c.Close()
    },
)

Corresponding YAML configuration:

http:
  clients:
    serviceA:  # <- "serviceA" becomes the bean name
      baseURL: "http://a.example.com"
      timeout: 30s
    serviceB:  # <- "serviceB" becomes the bean name
      baseURL: "http://b.example.com"
      timeout: 60s

func Module ¶ added in v1.2.3

func Module(c PropertyCondition, fn ModuleFunc)

Module registers a configuration module that is conditionally activated based on property values.

Limitations:

• MUST be called during init phase (will panic otherwise)
• Condition is evaluated at module execution time, not registration time
• Module functions cannot be called directly; they are managed by the framework

Use cases:

• Starter modules that auto-configure based on classpath/dependencies
• Feature modules that activate based on configuration flags
• Modular application architecture

Example:

gs.Module(gs.OnProperty("redis.enabled"),
func(r gs.BeanProvider, p flatten.Storage) error {
    r.Provide(NewRedisClient)
    return nil
})

func Provide ¶

func Provide(objOrCtor any, args ...Arg) *gs_bean.BeanDefinition

Provide registers a global bean definition. It must be called during package initialization (init phase). Calling it after application configuration has started will panic. It accepts either an existing instance or a constructor function. The optional args are used to bind parameters for the constructor or to provide explicit injection values.

Parameters:

• objOrCtor: bean instance (struct pointer) or constructor function
• args: optional arguments for parameter binding

Limitations:

• MUST be called during init phase (before application startup)
• Will panic if called after initialization is complete
• Bean must be a reference type (pointer), not a value type
• Constructor functions must have signature: func(...)bean or func(...)(bean, error)

Example:

// Register an instance
gs.Provide(&MyService{})

// Register a constructor with arguments
gs.Provide(NewMyService, gs.TagArg("${config.key}"))

// Chain configuration
gs.Provide(&Logger{}).Name("default").InitMethod("Start")

func RegisterExpressFunc ¶ added in v1.2.0

func RegisterExpressFunc(name string, fn any)

RegisterExpressFunc registers a custom expression function that can be used inside conditional expressions. It should be called during application initialization.

func Run ¶

func Run()

Run creates and starts a new application using default settings. Blocks until termination signal is received (SIGINT/SIGTERM).

func RunAsync ¶ added in v1.2.2

func RunAsync() (stop func(), err error)

RunAsync runs the application asynchronously and returns a function to stop the application. Convenience wrapper that creates a new AppStarter.

Returns:

• stop: Function to gracefully shutdown the application
• err: Error if application failed to start (nil on success)

Usage:

stop, err := gs.RunAsync()
if err != nil {
    log.Fatal(err)
}
defer stop() // Ensure cleanup
// ... do work ...

func RunTest ¶ added in v1.3.0

func RunTest(t *testing.T, f any)

RunTest runs a test function using a new application instance. Convenience wrapper that creates a fresh AppStarter for testing.

Parameters:

• t: Testing.T instance for test reporting and failure handling
• f: Test function accepting exactly one pointer-to-struct argument

Requirements:

• Test function signature: func(*TestStruct)
• TestStruct fields can use autowire/value tags for injection
• Struct is registered as root bean with full dependency injection

Example:

func TestExample(t *testing.T) {
    gs.RunTest(t, func(ts *struct {
        DB *Database `autowire:""`
    }) {
        // ts.DB is auto-injected
        result := ts.DB.Query(...)
        assert.NotNil(t, result)
    })
}