# Ferret
Try it!
Docs
CLI
Test runner
Web worker
---
## Explore Ferret v2
Ferret v2 is currently in alpha. You can try the new syntax in the playground and read more about the design behind the new runtime and language capabilities:
- [Try Ferret v2 in the Playground](https://ferretlang.org/try/)
- [On the Road to Ferret v2](https://ferretlang.org/blog/ferret-v2-announcement/)
- [Inside Ferret v2: The New Execution Model](https://ferretlang.org/blog/ferret-v2-execution-model/)
- [Inside Ferret v2: New Language Capabilities](https://ferretlang.org/blog/ferret-v2-new-syntax/)
---
> **Notice:** This branch contains the upcoming **Ferret v2**. For the stable v1 release, please visit [Ferret v1](https://github.com/MontFerret/ferret/tree/v1).
---
## What is it?
Ferret is a declarative-first, expression-oriented embedded language and runtime for data automation.
FQL combines querying, transformation, synchronization, and structured results with host-defined values and capabilities. Applications can embed the runtime and decide exactly which functions, modules, data, and external operations a program can use.
The language keeps a declarative core and adds domain-oriented orchestration plus constrained mutable state for automation that cannot be expressed as a pure data transformation. It is deliberately focused rather than a general-purpose scripting language.
### Features
- Purpose-built declarative language for querying, transforming, synchronizing, and automating structured data
- Embeddable Go runtime with reusable compiled plans and isolated execution sessions
- Capability-based host values for exposing application objects, resources, and external systems directly to FQL
- Unified query model for browsers, APIs, databases, documents, and custom data sources
- Extensible runtime through namespaced functions, modules, hooks, and custom value types
- Event-driven synchronization and dispatch for interacting with asynchronous and stateful resources
- Managed resource lifecycle for files, connections, cursors, streams, and other host resources
- Bytecode VM and portable programs for efficient repeated execution and precompiled artifacts
## Getting started
```bash
go get github.com/MontFerret/ferret/v2@latest
```
There are currently two ways to start with Ferret v2:
- Native v2 API - recommended for new projects
- `compat` module - recommended as a first migration step for existing v1 integrations
Use `github.com/MontFerret/ferret/v2` and `ferret.New(opts...)` for Native
embedding. For integrations using `github.com/MontFerret/api`, the official
adapter is the separate `github.com/MontFerret/ferret/v2/uapi` package.
`uapi.New(version, opts...)` creates and owns a Native engine; runtime Close
closes it. `uapi.Wrap(native, version)` borrows an existing engine; its Close is
a no-op that leaves both usable. Both retain the supplied Ferret Core version
for `Runtime.Version(ctx)`. Settle work and close sessions and plans before
their owning runtime or borrowed engine. See the
[Universal adapter guide](docs/maintainers/architecture/universal-api.md) for the supported options
and lifecycle contract.
### New projects
Use the native v2 API built around the following flow:
```
Engine -> compile query -> create session -> run -> collect or consume
```
```go
package main
import (
"context"
"fmt"
"log"
"github.com/MontFerret/ferret/v2"
)
func main() {
ctx := context.Background()
eng, err := ferret.New()
if err != nil {
log.Fatal(err)
}
defer eng.Close()
plan, err := eng.Compile(ctx, ferret.NewAnonymousSource(`return 1 + 1`))
if err != nil {
log.Fatal(err)
}
defer plan.Close()
session, err := plan.NewSession(ctx)
if err != nil {
log.Fatal(err)
}
defer session.Close()
output, err := session.Run(ctx)
if err != nil {
log.Fatal(err)
}
defer output.Close()
content, err := output.Collect(ctx)
if content != nil {
fmt.Println(string(content.Data))
}
if err != nil {
log.Print(err)
}
}
```
`Run` executes and encodes eagerly. Its nil error means an output handle was
obtained; `Collect` or `Consume` reports terminal execution and cleanup errors.
Keep the invocation context alive through consumption. Available content may
accompany an error. Consume outputs used only for side effects, and close outputs
you abandon. See the [consumable-output migration](docs/maintainers/architecture/consumable-output-migration.md).
### Migration from v1
Ferret v2 introduces a new architecture and public API, so existing Go applications should migrate in two stages: first to the v2 compatibility API, then incrementally to the native v2 API.
Run the [`ferret migrate`](https://github.com/MontFerret/cli#migrating-embedded-ferret-applications) command from anywhere inside the application's Go module:
```bash
ferret migrate --dry-run # List the files that would change
ferret migrate --print # Print a unified diff without changing files
ferret migrate # Apply the migration
```
The command rewrites the documented v1 imports to their v2 compatibility packages, updates `go.mod` and `go.sum` as required by those rewrites, and formats changed Go files. Generated, vendored, and nested-module files are left untouched. Unsupported v1 imports are reported as manual follow-up; if the project vendors dependencies, run `go mod vendor` after applying the migration.
This is only the mechanical compatibility stage. The command does not convert application logic to the native v2 API or migrate drivers and other unsupported v1 packages. Running it again on an already-migrated compatibility project is a no-op and does not upgrade the Ferret v2 dependency merely because the CLI is newer.
After applying the migration, address any reported manual follow-up, build and test the application, and then migrate to the native v2 API over time. The compatibility layer is a migration aid, not the long-term preferred API; new projects should use the native v2 packages directly.
### Alpha status
Ferret v2 is currently in active development.
Alpha releases are intended for early adopters, experimentation, and feedback. Some APIs and language features may still change before the stable v2 release.
## Maintainers
- [Maintainer documentation](docs/maintainers/README.md)
- [Versioned Ferret Core API Reference](docs/maintainers/reference/core-api.md)
## Support Ferret
Ferret is supported by organizations and community members who help fund its continued development. [View all supporters](https://ferretlang.org/sponsor/).