documents

Documentation

Index

• type BatchError
  • func (e *BatchError) Error() string
  • func (e *BatchError) Unwrap() []error
• type CollectionOf
  • func Collection[T any](b whisker.Backend, name string) *CollectionOf[T]
  • func (c *CollectionOf[T]) Count(ctx context.Context) (int64, error)
  • func (c *CollectionOf[T]) Delete(ctx context.Context, id string) error
  • func (c *CollectionOf[T]) DeleteMany(ctx context.Context, ids []string) error
  • func (c *CollectionOf[T]) Exists(ctx context.Context, id string) (bool, error)
  • func (c *CollectionOf[T]) Insert(ctx context.Context, doc *T) error
  • func (c *CollectionOf[T]) InsertMany(ctx context.Context, docs []*T) error
  • func (c *CollectionOf[T]) Load(ctx context.Context, id string) (*T, error)
  • func (c *CollectionOf[T]) LoadMany(ctx context.Context, ids []string) ([]*T, error)
  • func (c *CollectionOf[T]) Query() *Query[T]
  • func (c *CollectionOf[T]) Update(ctx context.Context, doc *T) error
  • func (c *CollectionOf[T]) UpdateMany(ctx context.Context, docs []*T) error
  • func (c *CollectionOf[T]) Where(field, op string, value any) *Query[T]
• type Direction
• type Query
  • func (q *Query[T]) After(value any) *Query[T]
  • func (q *Query[T]) Count(ctx context.Context) (int64, error)
  • func (q *Query[T]) Execute(ctx context.Context) ([]*T, error)
  • func (q *Query[T]) Exists(ctx context.Context) (bool, error)
  • func (q *Query[T]) Limit(n uint64) *Query[T]
  • func (q *Query[T]) Offset(n uint64) *Query[T]
  • func (q *Query[T]) OrderBy(field string, dir Direction) *Query[T]
  • func (q *Query[T]) Where(field, op string, value any) *Query[T]

Types

type BatchError

type BatchError struct {
	Op     string
	Total  int
	Errors map[string]error
}

BatchError collects per-document errors from a batch operation. The Errors map is keyed by document ID.

func (*BatchError) Error

func (e *BatchError) Error() string

func (*BatchError) Unwrap

func (e *BatchError) Unwrap() []error

Unwrap returns all inner errors, enabling errors.Is and errors.As to match through the batch.

type CollectionOf

type CollectionOf[T any] struct {
	// contains filtered or unexported fields
}

CollectionOf provides typed CRUD operations for a named document collection. Documents are stored as JSONB in a whisker_{name} table with automatic schema creation and optional index management.

func Collection

func Collection[T any](b whisker.Backend, name string) *CollectionOf[T]

Collection creates a new typed collection backed by the given store.

func (*CollectionOf[T]) Count

func (c *CollectionOf[T]) Count(ctx context.Context) (int64, error)

Count returns the total number of documents in the collection.

func (*CollectionOf[T]) Delete

func (c *CollectionOf[T]) Delete(ctx context.Context, id string) error

Delete removes a document by ID. Returns ErrNotFound if absent.

func (*CollectionOf[T]) DeleteMany

func (c *CollectionOf[T]) DeleteMany(ctx context.Context, ids []string) error

DeleteMany removes multiple documents by ID in a single DELETE with WHERE IN. Uses RETURNING id to identify which requested IDs were actually deleted, then reports missing IDs via a BatchError. Found documents are always deleted, even when some IDs are missing.

func (*CollectionOf[T]) Exists

func (c *CollectionOf[T]) Exists(ctx context.Context, id string) (bool, error)

Exists checks whether a document with the given ID exists.

func (*CollectionOf[T]) Insert

func (c *CollectionOf[T]) Insert(ctx context.Context, doc *T) error

Insert stores a new document. The document must have a non-empty ID field. On success, the document's Version is set to 1.

func (*CollectionOf[T]) InsertMany

func (c *CollectionOf[T]) InsertMany(ctx context.Context, docs []*T) error

InsertMany stores multiple documents in a single INSERT statement. All documents must have non-empty ID fields. On success, each document's Version is set to 1. On a unique constraint violation, the returned BatchError may attribute the failure to all document IDs because PostgreSQL does not identify the specific conflicting row in a multi-row insert. When possible, the conflicting ID is extracted from the PG error detail.

func (*CollectionOf[T]) Load

func (c *CollectionOf[T]) Load(ctx context.Context, id string) (*T, error)

Load retrieves a single document by ID. Returns ErrNotFound if absent.

func (*CollectionOf[T]) LoadMany

func (c *CollectionOf[T]) LoadMany(ctx context.Context, ids []string) ([]*T, error)

LoadMany retrieves multiple documents by ID in a single SELECT with WHERE IN. Documents are returned in no guaranteed order. If some IDs are missing, the found documents are returned alongside a BatchError listing the missing IDs.

func (*CollectionOf[T]) Query

func (c *CollectionOf[T]) Query() *Query[T]

Query starts a fluent query builder for this collection.

func (*CollectionOf[T]) Update

func (c *CollectionOf[T]) Update(ctx context.Context, doc *T) error

Update replaces an existing document's data. If the document has a Version field, optimistic concurrency is enforced — a concurrent modification returns ErrConcurrencyConflict. On success, Version is incremented.

func (*CollectionOf[T]) UpdateMany

func (c *CollectionOf[T]) UpdateMany(ctx context.Context, docs []*T) error

UpdateMany updates multiple documents in a single UPDATE...FROM VALUES statement. Optimistic concurrency is enforced per document — if any document's version has changed since it was loaded, the entire batch fails with a BatchError identifying which documents had version conflicts vs which were missing.

func (*CollectionOf[T]) Where

func (c *CollectionOf[T]) Where(field, op string, value any) *Query[T]

Where starts a query with an initial filter condition.

type Direction

type Direction string

Direction specifies sort order for query results.

const (
	Asc  Direction = "ASC"
	Desc Direction = "DESC"
)

type Query

type Query[T any] struct {
	// contains filtered or unexported fields
}

Query builds and executes filtered, sorted, paginated queries against a document collection. All methods return a new Query (immutable chaining).

func (*Query[T]) After

func (q *Query[T]) After(value any) *Query[T]

After enables cursor-based pagination. Requires at least one OrderBy clause. Returns documents after the given value in the sort order.

func (*Query[T]) Count

func (q *Query[T]) Count(ctx context.Context) (int64, error)

Count returns the number of documents matching the query conditions.

func (*Query[T]) Execute

func (q *Query[T]) Execute(ctx context.Context) ([]*T, error)

Execute runs the query and returns matching documents.

func (*Query[T]) Exists

func (q *Query[T]) Exists(ctx context.Context) (bool, error)

Exists returns true if at least one document matches the query conditions.

func (*Query[T]) Limit

func (q *Query[T]) Limit(n uint64) *Query[T]

Limit caps the number of results returned.

func (*Query[T]) Offset

func (q *Query[T]) Offset(n uint64) *Query[T]

Offset skips the first n results.

func (*Query[T]) OrderBy

func (q *Query[T]) OrderBy(field string, dir Direction) *Query[T]

OrderBy adds a sort clause. Multiple calls add secondary sort keys.

func (*Query[T]) Where

func (q *Query[T]) Where(field, op string, value any) *Query[T]

Where adds a filter condition. Field names are resolved to JSONB paths automatically. Supported operators: =, !=, >, <, >=, <=.