Using as a Library¶

Blink can be used as a library in your Go projects, providing programmatic access to its file system watching capabilities.

Installation¶

To use Blink as a library, add it to your Go project:

go get github.com/TFMV/blink

Basic Usage¶

Here's a simple example of using Blink as a library:

package main

import (
    "time"
    "github.com/TFMV/blink/pkg/blink"
)

func main() {
    // Set verbose mode
    blink.SetVerbose(true)

    // Start the event server
    blink.EventServer(
        ".",                  // Directory to watch
        "*",                  // Allow all origins
        ":12345",             // Listen on port 12345
        "/events",            // Event path
        100*time.Millisecond, // Refresh duration
    )

    // Wait for events
    select {}
}

Event Streaming¶

You can choose between WebSockets, Server-Sent Events (SSE), or both for streaming events:

package main

import (
    "time"
    "github.com/TFMV/blink/pkg/blink"
)

func main() {
    // Start the event server with WebSockets
    blink.EventServer(
        ".",                  // Directory to watch
        "*",                  // Allow all origins
        ":12345",             // Listen on port 12345
        "/events",            // Event path
        100*time.Millisecond, // Refresh duration
        blink.WithStreamMethod(blink.StreamMethodWebSocket),
    )

    select {}
}

Available stream methods:

blink.StreamMethodSSE: Use Server-Sent Events (default)
blink.StreamMethodWebSocket: Use WebSockets
blink.StreamMethodBoth: Use both SSE and WebSockets

When using blink.StreamMethodBoth, Blink will serve:

SSE events at the path specified (e.g., /events)
WebSocket events at the same path with /ws appended (e.g., /events/ws)

Event Filtering¶

You can filter events based on file patterns or event types:

package main

import (
    "time"
    "github.com/TFMV/blink/pkg/blink"
)

func main() {
    // Create a filter
    filter := blink.NewEventFilter()

    // Set include patterns
    filter.SetIncludePatterns("*.js,*.css,*.html")

    // Set exclude patterns
    filter.SetExcludePatterns("node_modules,*.tmp")

    // Set include event types
    filter.SetIncludeEvents("write,create")

    // Set ignore event types
    filter.SetIgnoreEvents("chmod")

    // Start the event server with the filter
    blink.EventServer(
        ".",                  // Directory to watch
        "*",                  // Allow all origins
        ":12345",             // Listen on port 12345
        "/events",            // Event path
        100*time.Millisecond, // Refresh duration
        blink.WithFilter(filter),
    )

    select {}
}

Webhooks¶

You can configure webhooks to send HTTP requests when file changes occur:

package main

import (
    "time"
    "github.com/TFMV/blink/pkg/blink"
)

func main() {
    // Start the event server with webhooks
    blink.EventServer(
        ".",                  // Directory to watch
        "*",                  // Allow all origins
        ":12345",             // Listen on port 12345
        "/events",            // Event path
        100*time.Millisecond, // Refresh duration
        // Webhook options
        blink.WithWebhook(
            "https://example.com/webhook", 
            "POST",
            map[string]string{
                "Authorization": "Bearer token",
                "Content-Type": "application/json",
            },
            10*time.Second,
            500*time.Millisecond,
            5,
        ),
    )

    select {}
}

Combining Options¶

You can combine multiple options:

package main

import (
    "time"
    "github.com/TFMV/blink/pkg/blink"
)

func main() {
    // Create a filter
    filter := blink.NewEventFilter()
    filter.SetIncludePatterns("*.js,*.css,*.html")
    filter.SetExcludePatterns("node_modules,*.tmp")
    filter.SetIncludeEvents("write,create")
    filter.SetIgnoreEvents("chmod")

    // Start the event server with multiple options
    blink.EventServer(
        ".",                  // Directory to watch
        "*",                  // Allow all origins
        ":12345",             // Listen on port 12345
        "/events",            // Event path
        100*time.Millisecond, // Refresh duration
        // Options
        blink.WithFilter(filter),
        blink.WithStreamMethod(blink.StreamMethodBoth),
        blink.WithWebhook(
            "https://example.com/webhook", 
            "POST",
            map[string]string{
                "Authorization": "Bearer token",
                "Content-Type": "application/json",
            },
            10*time.Second,
            500*time.Millisecond,
            5,
        ),
    )

    select {}
}

Custom Event Handling¶

If you want to handle events directly instead of using the built-in server, you can use the Watcher:

package main

import (
    "fmt"
    "time"
    "github.com/TFMV/blink/pkg/blink"
)

func main() {
    // Create a watcher configuration
    config := blink.WatcherConfig{
        RootPath:        ".",
        Recursive:       true,
        HandlerDelay:    100 * time.Millisecond,
        PollInterval:    4 * time.Second,
        IncludePatterns: []string{"*.js", "*.css", "*.html"},
        ExcludePatterns: []string{"node_modules", "*.tmp"},
        IncludeEvents:   []string{"write", "create"},
        IgnoreEvents:    []string{"chmod"},
    }

    // Create a watcher
    watcher, err := blink.NewWatcher(config)
    if err != nil {
        panic(err)
    }
    defer watcher.Close()

    // Start the watcher
    if err := watcher.Start(); err != nil {
        panic(err)
    }

    // Handle events
    for {
        select {
        case events := <-watcher.Events():
            for _, event := range events {
                fmt.Printf("Event: %s %s\n", event.Op.String(), event.Name)
            }
        case err := <-watcher.Errors():
            fmt.Printf("Error: %v\n", err)
        }
    }
}