search

package
v0.23.0-beta.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0, BSD-3-Clause, MIT Imports: 6 Imported by: 0

Documentation

Overview

Package search is the search contract of Nanostack DB: the page, sort and cursor types that every layer shares, the limits of a search, its errors, and All, which reads every page of a search.

The package imports the standard library only, so an API, domain or test package can import it with no SQL dialect and no database driver. The code that runs a search on a database is in other packages of this module.

A search answers a page (Result) of the rows that match its filters. A page starts after a cursor (Pagination.Cursor, the NextCursor of the previous page) or at an offset, never both. CheckPage is the rule for a page that every search applies, for HTTP and Go callers alike.

The errors fall into two groups. A client error (IsClientError) is a request the caller can fix: the HTTP edge answers it with a 400, and core/log logs it at Debug. ErrUnscoped is a programming error: the HTTP edge answers it with a 500, and core/log logs it at Error.

Index

Examples

Constants

View Source
const (
	// MaxLimit is the largest page a search serves.
	MaxLimit = 1000
	// MaxCursorLength bounds the opaque cursor a client may send back. A
	// cursor carries one value per ordering column, so a few hundred bytes is
	// typical. The bound leaves room for several text sort values of 1,000
	// characters each, which is why a sortable text column must be bounded
	// (VARCHAR(255) or a validated length): a longer value would issue a
	// cursor that DecodeCursor refuses.
	MaxCursorLength = 8192
	// MaxInValues is the largest number of values of one set filter (In,
	// InFold or ContainsAny). More values are ErrTooManyValues. PostgreSQL
	// binds at most 65535 parameters per statement.
	MaxInValues = 1000
	// MaxTermLength is the largest number of characters of one text term
	// (Contains). A longer term is ErrTermTooLong.
	MaxTermLength = 1000
)

Limits of a search. A product's API contract may set lower limits; the runtime never serves more than these.

Variables

View Source
var (
	// ErrInvalidCursor reports a cursor that cannot continue this search: it
	// is malformed, too long, or was issued for a different ordering.
	ErrInvalidCursor error = &clientError{"search: invalid cursor"}

	// ErrCursorWithOffset reports a page that sets both a cursor and a
	// non-zero offset. A cursor already says where the page starts.
	ErrCursorWithOffset error = &clientError{"search: cursor cannot be combined with offset"}

	// ErrUnknownSort reports a sort field the search cannot order by. A
	// silent fallback to the default order would answer another question
	// than the client asked.
	ErrUnknownSort error = &clientError{"search: unknown sort field"}

	// ErrInvalidLimit reports a page size outside 1 to MaxLimit.
	ErrInvalidLimit error = &clientError{"search: limit out of range"}

	// ErrInvalidOffset reports a negative offset.
	ErrInvalidOffset error = &clientError{"search: offset out of range"}

	// ErrTooManyValues reports a set filter with more than MaxInValues values.
	ErrTooManyValues error = &clientError{"search: too many values"}

	// ErrTermTooLong reports a text term longer than MaxTermLength characters.
	ErrTermTooLong error = &clientError{"search: term too long"}
)

The client errors of a search. Each answers HTTP 400, and each has a Level method that returns slog.LevelDebug, so core/log's LevelFor logs it at Debug through any wrapping: the API refusing a bad request is not the service failing.

View Source
var ErrUnscoped = errors.New("search: no tenant scope; build the search from its generated spec")

ErrUnscoped reports a search that has no tenant scope: it was not built from its generated spec, a scope value is zero (an empty id, a nil UUID), or a context scope returned no condition. It is a programming error, not a client error: it has no Level method, so core/log logs it at Error, and the HTTP edge answers it with a 500.

Functions

func All

func All[Q Pager[Q], R any](ctx context.Context, q Q, page func(context.Context, Q) (Result[R], error)) ([]R, error)

All reads every page of q through page and returns every item, in order. It serves internal batch reads; an API pages instead. It never changes the caller's q. It stops at the first error of page, and before each page when ctx is done. A search with no match gives an empty slice, not nil.

All also stops with an error when a page gives back the cursor it started after. Such a page does not move forward, and without the check All reads it again until ctx ends; an internal batch read often has no deadline.

Example
items, err := search.All(context.Background(), numbers{n: 3}, pageOfNumbers)
fmt.Println(items, err)
Output:
[1 2 3] <nil>

func CheckPage

func CheckPage(p Pagination) error

CheckPage reports whether a search can serve the page. It refuses a limit outside 1 to MaxLimit (ErrInvalidLimit) and a negative offset (ErrInvalidOffset), then applies Validate. An HTTP request passes the API contract first; CheckPage applies the same rule to a Go caller.

Example
package main

import (
	"errors"
	"fmt"

	"github.com/nanostack-dev/nanostack-framework/db/search"
)

func main() {
	fmt.Println(search.CheckPage(search.Pagination{Limit: 20}))
	err := search.CheckPage(search.Pagination{Limit: 5000})
	fmt.Println(errors.Is(err, search.ErrInvalidLimit), search.IsClientError(err))
}
Output:
<nil>
true true

func EncodeCursor

func EncodeCursor(order string, values []any) (string, error)

EncodeCursor builds the opaque token for the row whose ordering values are given. Values must be JSON-encodable; nil encodes a SQL NULL. A token longer than MaxCursorLength is an error of the search, not of the client: sort only on bounded columns.

func IsClientError

func IsClientError(err error) bool

IsClientError reports whether err is a search error the caller caused, at any depth of wrapping. Each answers HTTP 400. ErrUnscoped is not one, and it wins: an error that also holds ErrUnscoped (for example through errors.Join) is not a client error, because a missing tenant scope is a programming error even when the request was also bad.

core/log's LevelFor reads the first Level method it finds, and core cannot import db. So a join of a client error and ErrUnscoped can still log at Debug there. Wrap ErrUnscoped alone, never in a join with a client error.

Types

type Cursor

type Cursor struct {
	// Order identifies the ordering, for example "created_at:DESC,id:DESC".
	// A cursor only continues the ordering it was issued for.
	Order string
	// Values holds one JSON value per ordering column, in order. A JSON null
	// is a SQL NULL.
	Values []json.RawMessage
}

Cursor is the decoded form of an opaque pagination token: the ordering it was issued for and the last row's value for each ordering column.

A cursor is position, not authority. It is neither signed nor encrypted: tenant scope and filters always come from the request, so an edited cursor can at most move the start of a page inside rows the caller may already read. Never put anything into a cursor that the caller may not see.

func DecodeCursor

func DecodeCursor(token string) (Cursor, error)

DecodeCursor parses a token that EncodeCursor produced. Every failure wraps ErrInvalidCursor, so a caller translates them with one errors.Is.

type Pager

type Pager[Q any] interface {
	After(cursor string) Q
}

Pager is a search that can continue after a cursor. After returns a copy that starts after cursor; it never changes the search it is called on.

type Pagination

type Pagination struct {
	Limit  int32 `json:"limit"  validate:"required,min=1,max=1000"`
	Offset int32 `json:"offset" validate:"min=0"`
	// Cursor is an opaque token from Result.NextCursor. Empty starts at the
	// first row.
	Cursor string `json:"cursor,omitempty" validate:"max=8192"`
}

Pagination selects one page. Cursor is the standard: pass the previous result's NextCursor to continue. Offset remains for clients that jump to a page number, and cannot be combined with a cursor.

func (Pagination) Validate

func (p Pagination) Validate() error

Validate reports whether the cursor of the page can run: a cursor must fit MaxCursorLength and cannot be combined with a non-zero offset. It does not check the limit and the offset; CheckPage does.

type Result

type Result[T any] struct {
	Items []T
	// Total counts every match of the filters, not only this page or the
	// rows after the cursor.
	Total int64
	// Count is len(Items).
	Count int
	// NextCursor continues the search after the last item. It is empty when
	// no rows follow, so an empty NextCursor is the end of the iteration.
	NextCursor string
}

Result is one page of a search.

func (Result[T]) HasMore

func (r Result[T]) HasMore() bool

HasMore reports whether a following page exists.

type Sort

type Sort[F ~string] struct {
	Field     F             `validate:"required"`
	Direction SortDirection `validate:"required,oneof=ASC DESC"`
}

Sort is one requested sort key. The validate tags stay for hand-written searches that validate their request structs.

type SortDirection

type SortDirection string

SortDirection is the direction of one sort key.

const (
	SortAscending  SortDirection = "ASC"
	SortDescending SortDirection = "DESC"
)

The sort directions. They are the wire values of the API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL