data

type AllowStale bool

type AppendBatchRequest struct {
	// AppendRequests allows you to set
	AppendRequests []*AppendRequest
	// (option) Atomic indicates that all deletes must succeed or none will (i.e. that they
	// are applied in a transaction), and that other operations will be serialized
	// ahead or behind this operation.
	Atomic IsAtomic
	// ParentPath is the path all these items share.
	// Example: [/state-washington/city-seattle]/[person]-<id> the first group is the ParentPath, and the second is the ItemType
	ParentPath string
}

type AppendBatchResponse struct {
	RawItem *RawItem
	Error   error
}

type AppendIDAssignment int

type AppendRequest struct {
	// ItemType "is the item path without the "id" part because we're appending it.
	// Example: "person-<id>" you would omit the "-<id>" for "person"
	ItemType string
	// You JSON or proto data to append.
	Data any
	// IDAssignment allows per item append id assignment. Read AppendIDAssignment for more choices.
	IDAssignment AppendIDAssignment
}

type Changed struct {
	Item *RawItem
}

type Client interface {
	// GetBatch retrieves one or more Items by their full key paths. This will return any
	// of the Items that exist. It will fail if not all of the GetItem requests are
	// under the same root item path, or if the caller does not have permission to
	// read Items. Use Query if you want to retrieve multiple items but don't
	// already know the full key paths of the items you want to get.
	GetBatch(ctx context.Context, request GetRequest) ([]*RawItem, error)

	// Get retrieves one Item by their full key paths. It will fail if the caller does
	// not have permission to read Items. Use Query if you want to retrieve multiple
	// items but don't already know the full key paths of the items you want to get.
	// Use GetBatch if you want to retrieve multiple items by their full key paths.
	Get(ctx context.Context, itemPath string, options ...GetOptions) (*RawItem, error)

	// PutBatch adds one or more Items to the Store, or replaces the Items if they
	// already exist at that path.
	//
	// This will fail if
	//   - not all the PutData requests are under the same root item path.
	//   - any of the PutData requests' write conditions fails.
	//   - the caller does not have permission to create Items.
	//
	// Additional Notes:
	// All puts in the request are applied atomically - there are no partial
	// successes. Data can be provided as either JSON, or as a proto encoded by a
	// previously agreed upon schema, or by some combination of the two.
	PutBatch(ctx context.Context, request PutBatchRequest) ([]*PutBatchResponse, error)

	// Put adds one Item to the Store, or replaces the Item if it
	// already exists at that path.
	//
	// This will fail if:
	//   - The caller does not have permission to create Items.
	//
	// Additional Notes:
	// The PutData is applied atomically - there are no partial
	// successes. Data can be provided as a struct that can be
	// marshalled/unmarshalled as JSON, or a struct that can be
	// serialized/deserialized as a proto.
	Put(ctx context.Context, path string, value any) (*RawItem, error)

	// AppendBatch adds one or more new Items to a parent path, automatically assigning
	// IDs via one of several selectable ID generation strategies (not all
	// strategies may be available to all store configurations or path types).
	// The new item is guaranteed not to overwrite an existing Item because the ID
	// is generated by the server. This differs from Put specifically because
	// of this ID assignment behavior, and it is recommended over Put for new
	// items where you do not want to assign IDs yourself. The assigned IDs will
	// be returned in the response. This operation will fail if the caller does
	// not have permission to create Items.
	AppendBatch(ctx context.Context, request AppendBatchRequest) ([]*AppendBatchResponse, error)

	// Append one new Items to a parent path, automatically assigning
	// an ID via one of several selectable ID generation strategies (not all
	// strategies may be available to all store configurations or path types).
	// The new item is guaranteed not to overwrite an existing Item because the ID
	// is generated by the server. This differs from Put specifically because
	// of this ID assignment behavior, and it is recommended over Put for new
	// items where you do not want to assign IDs yourself. The assigned ID will
	// be returned in the response. This operation will fail if the caller does
	// not have permission to create Items.
	Append(
		ctx context.Context,
		parentPath, itemType string,
		idAssignment AppendIDAssignment,
		data any,
	) (*RawItem, error)

	// DeleteBatch removes one or more Items from the Store by their full key paths. This
	// will fail if any Item does not exist, if not all of the DeleteItem requests
	// are under the same root item path, or if the caller does not have permission
	// to delete Items. Tombstones will be left for deleted items for some
	// predetermined time (TBD tombstone behavior). All deletes in the request are
	// applied atomically - there are no partial successes.
	DeleteBatch(ctx context.Context, request DeleteRequest) ([]*DeleteResponse, error)

	// Delete removes one Item from the Store by their full key paths. This
	// will fail if the Item does not exist, or if the caller does not have permission
	// to delete Items. Tombstones will be left for deleted items for some
	// predetermined time (TBD tombstone behavior).
	Delete(ctx context.Context, itemPath string) error

	// BeginList loads Items that start with a specified key path, subject to
	// additional filtering. The prefix must minimally contain a Group Key (an
	// item type and an item ID). BeginList will return an empty result set if
	// there are no items matching that key prefix. A token is returned from this
	// API that you can then pass to ContinueList to expand the result set, or to
	// SyncList to get updates within the result set. This can fail if the caller
	// does not have permission to read Items.
	BeginList(ctx context.Context, keyPath string, opts ...ListOptions) (ListResponse[*RawItem], error)

	// ContinueList takes the token from a BeginList call and returns the next
	// "page" of results based on the original query parameters and pagination
	// options. It has few options because it is a continuation of a previous list
	// operation. It will return a new  token which can be used for another
	// ContinueList call, and so on. The  token is the same one used by SyncList -
	// each time you call either ContinueList or SyncList, you should pass the
	// latest version of the token, and then use the new token from the result in
	// subsequent calls. You may interleave ContinueList and SyncList calls
	// however you like, but it does not make sense to make both calls in
	// parallel. Calls to ContinueList are tied to the authorization of the
	// original BeginList call, so if the original BeginList call was allowed,
	// ContinueList with its token should also be allowed.
	ContinueList(ctx context.Context, token []byte) (ListResponse[*RawItem], error)

	// NewTransaction starts a new transaction on a stream, and calls the handler with a Transaction object.
	// The handler can then interact with the transaction by calling Get, Put, Append, Delete, and List.
	// The transaction is committed when the handler returns, and the results are returned.
	NewTransaction(ctx context.Context, handler TransactionHandler) (*TransactionResults, error)

	// SyncList returns an iterator for a sync operation.
	SyncList(ctx context.Context, token []byte) (ListResponse[SyncResponse], error)
}

type ContinueOptions struct {
	// SortDirection is the direction to sort by. Default is Forward.
	SortDirection SortDirection
}

type DeleteRequest struct {
	ItemPaths []string
	// (option) Atomic indicates that all deletes must succeed or none will (i.e. that they
	// are applied in a transaction), and that other operations will be serialized
	// ahead or behind this operation.
	Atomic IsAtomic
}

type DeleteResponse struct {
	KeyPath string
	Error   error
}

type Deleted struct {
	KeyPath string
}

type GetOptions struct {
	// (option) AllowStale  indicates that you're okay with getting a slightly stale item,
	// that is, if you had just changed an item and then call GetItem, you might
	// get the old version of the item. This can result in improved performance,
	// availability, and cost.
	AllowStale AllowStale
}

type GetRequest struct {
	// ItemPaths is an array of the full path(s) to the item(s).
	ItemPaths []string
	// (option) AllowStale  indicates that you're okay with getting a slightly stale item,
	// that is, if you had just changed an item and then call GetItem, you might
	// get the old version of the item. This can result in improved performance,
	// availability, and cost.
	AllowStale AllowStale
	// (optional) Atomic indicates that all gets in this request should be executed
	// atomically relative to other requests - that is, it will retrieve the items
	// as they were at the same point in time. If this is false (the default),
	// then each get will be executed independently, meaning each get may be
	// interleaved with modifications by other requests.
	Atomic IsAtomic
}

type IsAtomic bool

type Item[T any] struct {
	*RawItem
	Data T
}

type ItemKey []*ItemKeyComponent

type ItemKeyComponent struct {
	// ItemType identifies the type of this item, which:
	//  1. Associates it with a type in schema (TBD)
	//  2. Determines which version counter / ID sequence to use for these items,
	//     for both ID assignment and change tracking.
	//
	// TODO: In the future we could represent this as an ordinal into a schema,
	// for more compact storage.
	ItemType string

	// ItemID is an optional, unique value that identifies this item among other
	// items of the same item type within its containing item type. The ID may be
	// omitted in cases where the item is a singleton. This ID may be
	// user-provided, or assigned automatically by append.
	//
	// Types that are assignable to ItemId:
	//
	//	*KeyValueUint
	//	*KeyValueString
	//	*KeyValueBinary
	ItemID KeyValue
}

type ItemMetadata struct {
	CreatedAt             time.Time
	LastModifiedAt        time.Time
	CreatedAtVersion      uint64
	LastModifiedAtVersion uint64
}

type KeyValue interface {
	fmt.Stringer
}

type KeyValueBinary struct {
	// binary_value allows users to supply arbitrary binary value keys, which is
	// good for things like UUIDs.
	Value []byte
}

type KeyValueInt struct {
	// Value is the int64 value of the key.
	Value int64
}

type KeyValueString struct {
	// string_value allows users to supply arbitrary keys as a string.
	Value string
}

type KeyValueUint struct {
	// uint_value is the common case of an unsigned 64-bit integer as an ID.
	// This is a great default for most IDs and is what AppendItem automatically
	// uses when assigning IDs.
	Value uint64
}

type ListOptions struct {
	// Limit is the maximum number of items to return. If 0, the server will default to unlimited.
	Limit uint32
	// SortableProperty is the property to sort by. Default is SortByKeyPath.
	SortableProperty SortableProperty
	// SortDirection is the direction to sort by. Default is Forward.
	SortDirection SortDirection
	// AllowStale indicates that you're okay with getting slightly stale items
	// that is, if you had just changed an item and then call a List operation,
	// you might get the old version of the item. This can result in improved
	// performance, availability, and cost.
	AllowStale AllowStale
}

type ListRequest struct {
	// KeyPathPrefix must be at least the root component but optionally contain any number of path components to narrow
	// your list result. Example: [/state-washington]/city - the first segment is the root component, this would return
	// all cities in washington. Separately, you could issue a list request with just `/state-washington` which would
	// return the item at "/state-washington"
	KeyPathPrefix string
}

type ListResponse[T any] interface {
	// Next reads an item of the stream, and populates Value() with the current item.
	Next() bool
	// Token returns the current token OR any error that occurred during iteration.
	Token() (*ListToken, error)
	// Value returns the current item in the iteration.
	Value() T
}

type ListToken struct {
	// token will never be nil
	Data []byte
	// can continue indicates if there are more results to fetch using ContinueList
	CanContinue bool
	// can sync indicates that you could call SyncList with this token later to
	// get updated items. This is determined by the type of store you're listing
	// from.
	CanSync bool
}

type PutBatchRequest struct {
	PutData []*PutData
	// (option) Atomic indicates that all puts must succeed or none will (i.e. that they
	// are applied in a transaction), and that other operations will be serialized
	// ahead or behind this operation.
	Atomic IsAtomic
}

type PutBatchResponse struct {
	*RawItem
	Error error
}

type PutData struct {
	KeyPath string
	Data    any
}

type RawItem struct {
	Key           ItemKey
	ItemType      string
	ParentKeyPath ItemKey
	JSONData      json.RawMessage
	ID            KeyValue
	Metadata      ItemMetadata
}

type Reset struct{}

type SortDirection int

type SortableProperty int

type SyncResponse interface {
	// IsSyncResponse is a marker method to indicate that a type is a SyncResponse.
	IsSyncResponse()
}

type Transaction interface {
	// Get one RawItem by its full key path.
	Get(item string) (*RawItem, error)

	// GetBatch one or more Items by their full key paths.
	GetBatch(items ...string) ([]*RawItem, error)

	// Put is a convenience method for adding a single Item to the Store, or replacing the RawItem if it exists at that path.
	Put(keyPath string, data any) error

	// PutBatch adds one or more Items to the Store, or replaces the Items if they exist at that path.
	// The metadata (create time/version + modified time/version)  for each PutData is returned only at the end of the transaction.
	PutBatch(items ...*PutData) error

	// Append adds one Item to a parent path, automatically assigning an ID.
	Append(prefix, itemType string, data any, idAssignment AppendIDAssignment) (string, error)

	// AppendBatch adds one or more new Items to a parent path, automatically assigning IDs.
	// The metadata (create time/version + modified time/version) for each AppendRequest is returned only at the end of the transaction.
	AppendBatch(prefix string, items ...*AppendRequest) ([]string, error)

	// Delete removes one or more Items from the Store by their full key paths.
	Delete(items ...string) error

	// BeginList loads Items that start with a specified key path, subject to additional filtering.
	// The returned ListResponse can be used to iterate over the stream of results for example:
	//	iter, err := txn.BeginList("/path/to/items")
	//	// handle err
	//	for iter.Continue() {
	//		item := iter.Item()
	//		// do something with item
	//	}
	//	err, token := iter.Token();
	//	// handle err and token
	BeginList(prefix string, options ...*ListOptions) (ListResponse[*RawItem], error)

	// ContinueList picks back up where this token left off. As with BeginList, you use the ListResponse to iterate over
	// the stream of results.
	ContinueList(token *ListToken) (ListResponse[*RawItem], error)
}

type TransactionHandler func(Transaction) error

type TransactionResults struct {
	// PutResponse contains the full result of each Put operation. This only comes
	// back with the transaction is finished message because full metadata isn't
	// available until then.
	PutResponse []*PutBatchResponse

	// AppendResponse contains the full result of each Append operation. This only
	// comes back with the TransactionFinished message because full metadata isn't
	// available until then.
	AppendResponse []*AppendBatchResponse

	// DeleteResponse contains the full result of each Delete operation. This only
	// comes back with the TransactionFinished message because full metadata isn't
	// available until then.
	DeleteResponse []*DeleteResponse

	// Did the commit finish (the alternative is that it was aborted/rolled back)
	Committed bool
}

type UpdateOutsideOfWindow struct {
	KeyPath string
}