resource

package
v0.5.11 Latest Latest
Warning

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

 Go to latest Published: Jan 26, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package resource supplies a generic Access[K, V] interface for CRUD operations on key-value pairs, backed by an in-memory and JSON file implementation.

Index

Constants

View Source 
const (
	ErrorResourceAlreadyExists = "resource already exists"
	ErrorResourceNotFound      = "resource not found"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Access 

type Access[K, V any] interface {
	Create(ctx context.Context, key K, value V) error
	Read(ctx context.Context, key K) (*V, error)
	ReadAll(ctx context.Context) ([]V, error)
	Update(ctx context.Context, key K, value V) error
	Delete(ctx context.Context, key K) error
}

Access specifies the CRUD operations for a resource using generics. It supports context.Context for cancellation and timeouts.

type InMemoryAccess added in v0.4.8 

type InMemoryAccess[K comparable, V any] struct {
	// contains filtered or unexported fields
}

InMemoryAccess is a generic access implementation backed by a mock, in-memory and JSON file.

func NewInMemoryAccess 

func NewInMemoryAccess[K comparable, V any]() *InMemoryAccess[K, V]

NewInMemoryAccess creates a new in-memory access.

func (*InMemoryAccess[K, V]) Create added in v0.4.8 

func (a *InMemoryAccess[K, V]) Create(ctx context.Context, key K, value V) error

Create creates a new resource.

func (*InMemoryAccess[K, V]) Delete added in v0.4.8 

func (a *InMemoryAccess[K, V]) Delete(ctx context.Context, key K) error

Delete deletes a resource.

func (*InMemoryAccess[K, V]) Read added in v0.4.8 

func (a *InMemoryAccess[K, V]) Read(ctx context.Context, key K) (*V, error)

Read reads a resource.

func (*InMemoryAccess[K, V]) ReadAll added in v0.4.8 

func (a *InMemoryAccess[K, V]) ReadAll(ctx context.Context) ([]V, error)

ReadAll reads all resources.

func (*InMemoryAccess[K, V]) Update added in v0.4.8 

func (a *InMemoryAccess[K, V]) Update(ctx context.Context, key K, value V) error

Update updates a resource.

type IndexFunc added in v0.4.7 

type IndexFunc[V any] func(V) string

IndexFunc extracts an index key from a value. Returns an empty string if the value should not be indexed.

type IndexedAccess added in v0.4.7 

type IndexedAccess[K comparable, V any] struct {
	// contains filtered or unexported fields
}

IndexedAccess wraps a resource.Access and maintains secondary indexes. It supports both unique and non-unique indexes (stored as lists of keys).

func NewIndexedAccess added in v0.4.7 

func NewIndexedAccess[K comparable, V any](access Access[K, V]) *IndexedAccess[K, V]

NewIndexedAccess creates a new indexed access wrapper.

func (*IndexedAccess[K, V]) AddIndex added in v0.4.7 

func (a *IndexedAccess[K, V]) AddIndex(name string, fn IndexFunc[V])

AddIndex adds a new secondary index. name is the unique name of the index. fn is the function to extract the index key from the value.

func (*IndexedAccess[K, V]) Create added in v0.4.7 

func (a *IndexedAccess[K, V]) Create(ctx context.Context, key K, value V) error

Create stores a new value and updates secondary indexes.

func (*IndexedAccess[K, V]) Delete added in v0.4.7 

func (a *IndexedAccess[K, V]) Delete(ctx context.Context, key K) error

Delete removes a value and its secondary index entries.

func (*IndexedAccess[K, V]) FindByIndex added in v0.4.7 

func (a *IndexedAccess[K, V]) FindByIndex(ctx context.Context, indexName string, indexKey string) ([]V, error)

FindByIndex retrieves values by a secondary index key.

func (*IndexedAccess[K, V]) FindOneByIndex added in v0.4.7 

func (a *IndexedAccess[K, V]) FindOneByIndex(ctx context.Context, indexName string, indexKey string) (*V, bool)

FindOneByIndex retrieves a single value by a secondary index key. Returns nil, false if not found.

func (*IndexedAccess[K, V]) Read added in v0.4.7 

func (a *IndexedAccess[K, V]) Read(ctx context.Context, key K) (*V, error)

Read retrieves a value by its primary key.

func (*IndexedAccess[K, V]) ReadAll added in v0.4.7 

func (a *IndexedAccess[K, V]) ReadAll(ctx context.Context) ([]V, error)

ReadAll retrieves all values.

func (*IndexedAccess[K, V]) Update added in v0.4.7 

func (a *IndexedAccess[K, V]) Update(ctx context.Context, key K, value V) error

Update updates an existing value and its secondary indexes.

type JsonFileAccess added in v0.1.51 

type JsonFileAccess[K comparable, V any] struct {
	// contains filtered or unexported fields
}

JsonFileAccess is a json file access.

func NewJsonFileAccess added in v0.1.51 

func NewJsonFileAccess[K comparable, V any](path string) *JsonFileAccess[K, V]

NewJsonFileAccess creates a new json file access.

func (*JsonFileAccess[K, V]) Create added in v0.1.51 

func (a *JsonFileAccess[K, V]) Create(ctx context.Context, key K, value V) error

Create creates a new resource.

func (*JsonFileAccess[K, V]) Delete added in v0.1.51 

func (a *JsonFileAccess[K, V]) Delete(ctx context.Context, key K) error

Delete deletes a resource.

func (*JsonFileAccess[K, V]) Read added in v0.1.51 

func (a *JsonFileAccess[K, V]) Read(ctx context.Context, key K) (*V, error)

Read reads a resource.

func (*JsonFileAccess[K, V]) ReadAll added in v0.1.53 

func (a *JsonFileAccess[K, V]) ReadAll(ctx context.Context) ([]V, error)

ReadAll reads all resources.

func (*JsonFileAccess[K, V]) Update added in v0.1.51 

func (a *JsonFileAccess[K, V]) Update(ctx context.Context, key K, value V) error

Update updates a resource.

type MockAccess added in v0.2.14 

type MockAccess[K, V any] struct {
	// contains filtered or unexported fields
}

MockAccess is a mock implementation of Access[K, V]. Each method has a corresponding mock function pointer (...Ptr). Use the builder-pattern to set the mock function pointers for each method. This allows for more flexible and readable test cases.

func NewMockAccess added in v0.2.14 

func NewMockAccess[K, V any]() *MockAccess[K, V]

NewMockAccess creates a new instance of MockAccess[K, V].

func (*MockAccess[K, V]) Create added in v0.2.14 

func (a *MockAccess[K, V]) Create(ctx context.Context, key K, value V) error

Create creates a new resource with the given key and value.

func (*MockAccess[K, V]) Delete added in v0.2.14 

func (a *MockAccess[K, V]) Delete(ctx context.Context, key K) error

Delete deletes a resource with the given key.

func (*MockAccess[K, V]) Read added in v0.2.14 

func (a *MockAccess[K, V]) Read(ctx context.Context, key K) (*V, error)

Read reads a resource with the given key.

func (*MockAccess[K, V]) ReadAll added in v0.2.14 

func (a *MockAccess[K, V]) ReadAll(ctx context.Context) ([]V, error)

ReadAll reads all resources.

func (*MockAccess[K, V]) Update added in v0.2.14 

func (a *MockAccess[K, V]) Update(ctx context.Context, key K, value V) error

Update updates a resource with the given key and value.

func (*MockAccess[K, V]) WithCreateFn added in v0.4.8 

func (a *MockAccess[K, V]) WithCreateFn(fn func(ctx context.Context, key K, value V) error) *MockAccess[K, V]

WithCreateFn sets the mock function pointer for creating a resource.

func (*MockAccess[K, V]) WithDeleteFn added in v0.4.8 

func (a *MockAccess[K, V]) WithDeleteFn(fn func(ctx context.Context, key K) error) *MockAccess[K, V]

WithDeleteFn sets the mock function pointer for deleting a resource.

func (*MockAccess[K, V]) WithReadAllFn added in v0.4.8 

func (a *MockAccess[K, V]) WithReadAllFn(fn func(ctx context.Context) ([]V, error)) *MockAccess[K, V]

WithReadAllFn sets the mock function pointer for reading all resources.

func (*MockAccess[K, V]) WithReadFn added in v0.4.8 

func (a *MockAccess[K, V]) WithReadFn(fn func(ctx context.Context, key K) (*V, error)) *MockAccess[K, V]

WithReadFn sets the mock function pointer for reading a resource.

func (*MockAccess[K, V]) WithUpdateFn added in v0.4.8 

func (a *MockAccess[K, V]) WithUpdateFn(fn func(ctx context.Context, key K, value V) error) *MockAccess[K, V]

WithUpdateFn sets the mock function pointer for updating a resource.

type PostgresAccess added in v0.5.5 

type PostgresAccess[K comparable, V any] struct {
	// contains filtered or unexported fields
}

PostgresAccess provides a simple key-value store using PostgreSQL.

func NewPostgresAccess added in v0.5.5 

func NewPostgresAccess[K comparable, V any](db *sql.DB) *PostgresAccess[K, V]

NewPostgresAccess creates a new instance of PostgresAccess.

func (*PostgresAccess[K, V]) Create added in v0.5.5 

func (a *PostgresAccess[K, V]) Create(ctx context.Context, key K, value V) error

Create inserts a new key-value pair into the table.

func (*PostgresAccess[K, V]) Delete added in v0.5.5 

func (a *PostgresAccess[K, V]) Delete(ctx context.Context, key K) error

Delete removes the key-value pair associated with the given key.

func (*PostgresAccess[K, V]) Init added in v0.5.5 

func (a *PostgresAccess[K, V]) Init(ctx context.Context) error

Init initializes the table and index.

func (*PostgresAccess[K, V]) Read added in v0.5.5 

func (a *PostgresAccess[K, V]) Read(ctx context.Context, key K) (*V, error)

Read returns the value associated with the given key.

func (*PostgresAccess[K, V]) ReadAll added in v0.5.5 

func (a *PostgresAccess[K, V]) ReadAll(ctx context.Context) ([]V, error)

ReadAll returns all values from the table.

func (*PostgresAccess[K, V]) Update added in v0.5.5 

func (a *PostgresAccess[K, V]) Update(ctx context.Context, key K, value V) error

Update updates the value associated with the given key.

type SearchOptions added in v0.5.11 

type SearchOptions struct {
	// TopK limits results to the K most similar items. Default: 10.
	TopK int

	// Threshold filters results below this similarity score. Default: 0.0.
	Threshold float64
}

SearchOptions configures similarity search behavior.

type SearchResult added in v0.5.11 

type SearchResult[K comparable, V any] struct {
	Key   K
	Value V
	Score float64
}

SearchResult represents a similarity search result.

type ShardedSparseAccess added in v0.5.9 

type ShardedSparseAccess[K comparable, V any] struct {
	// contains filtered or unexported fields
}

ShardedSparseAccess is a high-performance in-memory Access implementation using sharding for reduced lock contention and sparse-dense storage for cache-friendly iteration. It wraps efficiency.SparseSharding with context handling and CRUD error semantics.

func NewShardedSparseAccess added in v0.5.9 

func NewShardedSparseAccess[K comparable, V any](numShards int) *ShardedSparseAccess[K, V]

NewShardedSparseAccess creates a new sharded sparse access with the given number of shards. A typical value is 32 or runtime.NumCPU() * 4. If numShards <= 0, defaults to 32.

func NewShardedSparseAccessWithCapacity added in v0.5.9 

func NewShardedSparseAccessWithCapacity[K comparable, V any](numShards, capacityPerShard int) *ShardedSparseAccess[K, V]

NewShardedSparseAccessWithCapacity creates a new sharded sparse access with pre-allocated capacity per shard for better performance when size is known.

func (*ShardedSparseAccess[K, V]) Clear added in v0.5.9 

func (a *ShardedSparseAccess[K, V]) Clear()

Clear removes all elements from all shards.

func (*ShardedSparseAccess[K, V]) Create added in v0.5.9 

func (a *ShardedSparseAccess[K, V]) Create(ctx context.Context, key K, value V) error

Create creates a new resource.

func (*ShardedSparseAccess[K, V]) Delete added in v0.5.9 

func (a *ShardedSparseAccess[K, V]) Delete(ctx context.Context, key K) error

Delete deletes a resource.

func (*ShardedSparseAccess[K, V]) ForEach added in v0.5.9 

func (a *ShardedSparseAccess[K, V]) ForEach(fn func(K, V) bool)

ForEach iterates over all elements. Stops if fn returns false. Iteration order is not guaranteed.

func (*ShardedSparseAccess[K, V]) Len added in v0.5.9 

func (a *ShardedSparseAccess[K, V]) Len() int

Len returns the total number of elements across all shards.

func (*ShardedSparseAccess[K, V]) Read added in v0.5.9 

func (a *ShardedSparseAccess[K, V]) Read(ctx context.Context, key K) (*V, error)

Read reads a resource.

func (*ShardedSparseAccess[K, V]) ReadAll added in v0.5.9 

func (a *ShardedSparseAccess[K, V]) ReadAll(ctx context.Context) ([]V, error)

ReadAll reads all resources.

func (*ShardedSparseAccess[K, V]) SearchSimilar added in v0.5.11 

func (a *ShardedSparseAccess[K, V]) SearchSimilar(
	ctx context.Context,
	scorer func(V) float64,
	opts SearchOptions,
) []SearchResult[K, V]

SearchSimilar finds the top-K most similar values using a custom scoring function. The scorer function is called for each value and should return a similarity score. Higher scores indicate more similarity. Results are sorted by descending score.

Example usage with cosine similarity: 

results := store.SearchSimilar(ctx, func(doc Document) float64 {
    return efficiency.CosineSimilarity(
        query.Indices, doc.Indices,
        query.Values, doc.Values,
        query.Norm, doc.Norm,
    )
}, resource.SearchOptions{TopK: 10, Threshold: 0.5})

func (*ShardedSparseAccess[K, V]) Update added in v0.5.9 

func (a *ShardedSparseAccess[K, V]) Update(ctx context.Context, key K, value V) error

Update updates a resource.

type SqliteAccess added in v0.4.8 

type SqliteAccess[K comparable, V any] struct {
	// contains filtered or unexported fields
}

SqliteAccess provides a simple key-value store using SQLite.

func NewSqliteAccess added in v0.2.25 

func NewSqliteAccess[K comparable, V any](db *sql.DB) *SqliteAccess[K, V]

NewSqliteAccess creates a new instance of SqliteAccess.

func (*SqliteAccess[K, V]) Create added in v0.4.8 

func (a *SqliteAccess[K, V]) Create(ctx context.Context, key K, value V) error

Create inserts a new key-value pair into the table.

func (*SqliteAccess[K, V]) Delete added in v0.4.8 

func (a *SqliteAccess[K, V]) Delete(ctx context.Context, key K) error

Delete removes the key-value pair associated with the given key.

func (*SqliteAccess[K, V]) Init added in v0.4.8 

func (a *SqliteAccess[K, V]) Init(ctx context.Context) error

Init initializes the table and index.

func (*SqliteAccess[K, V]) Read added in v0.4.8 

func (a *SqliteAccess[K, V]) Read(ctx context.Context, key K) (*V, error)

Read returns the value associated with the given key.

func (*SqliteAccess[K, V]) ReadAll added in v0.4.8 

func (a *SqliteAccess[K, V]) ReadAll(ctx context.Context) ([]V, error)

ReadAll returns all values from the table.

func (*SqliteAccess[K, V]) Update added in v0.4.8 

func (a *SqliteAccess[K, V]) Update(ctx context.Context, key K, value V) error

Update updates the value associated with the given key.

type YamlFileAccess added in v0.4.8 

type YamlFileAccess[K comparable, V any] struct {
	// contains filtered or unexported fields
}

YamlFileAccess is a yaml file access.

func NewYamlFileAccess added in v0.4.1 

func NewYamlFileAccess[K comparable, V any](path string) *YamlFileAccess[K, V]

NewYamlFileAccess creates a new yaml file access.

func (*YamlFileAccess[K, V]) Create added in v0.4.8 

func (a *YamlFileAccess[K, V]) Create(ctx context.Context, key K, value V) error

Create creates a new resource.

func (*YamlFileAccess[K, V]) Delete added in v0.4.8 

func (a *YamlFileAccess[K, V]) Delete(ctx context.Context, key K) error

Delete deletes a resource.

func (*YamlFileAccess[K, V]) Read added in v0.4.8 

func (a *YamlFileAccess[K, V]) Read(ctx context.Context, key K) (*V, error)

Read reads a resource.

func (*YamlFileAccess[K, V]) ReadAll added in v0.4.8 

func (a *YamlFileAccess[K, V]) ReadAll(ctx context.Context) ([]V, error)

ReadAll reads all resources.

func (*YamlFileAccess[K, V]) Update added in v0.4.8 

func (a *YamlFileAccess[K, V]) Update(ctx context.Context, key K, value V) error

Update updates a resource.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.