From 672ebb6306c095010c24a47a27d9e9aef9ca8ca5 Mon Sep 17 00:00:00 2001
From: Seebs <seebs@molecula.com>
Date: Wed, 11 Jan 2023 11:54:54 -0600
Subject: [PATCH] create keys package to unify types of index/field/view/shard
 keys

In developing QueryContext, I found it more expressive to have defined
types for index/field/view/shard keys. Then I wanted to refer to those
names from elsewhere. This package has no dependencies so anything
can import it and we can all agree on these types. Later I want to
migrate everything else to use these names.
---
 keys/doc.go  | 19 +++++++++++++++++++
 keys/keys.go | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 keys/doc.go
 create mode 100644 keys/keys.go

diff --git a/keys/doc.go b/keys/doc.go
new file mode 100644
index 000000000..e81acd466
--- /dev/null
+++ b/keys/doc.go
@@ -0,0 +1,19 @@
+// Copyright 2023 Molecula Corp (DBA FeatureBase). All rights reserved.
+package keys
+
+/*
+Package keys provides data types and structures that represent the logical
+structure of a featurebase database. This package is separate from the
+main package so it can be imported by other things which are also imported
+by the main package. That may some day become unnecessary.
+
+Featurebase's design sorts data into indexes (comparable to SQL tables),
+fields (comparable to SQL columns), views (no real comparison in SQL),
+and shards. The data denoted by {index, field, view, shard} is called a
+"fragment", and is itself a bitmap of 2^64 logical bits.
+
+Individual backend data storage may not correspond to this layout. The
+keys package provides data types representing how high-level Featurebase
+models and uses these data types, and does not address the question of how
+to make that make sense for a given storage backend.
+*/
diff --git a/keys/keys.go b/keys/keys.go
new file mode 100644
index 000000000..a36f44727
--- /dev/null
+++ b/keys/keys.go
@@ -0,0 +1,48 @@
+// Copyright 2023 Molecula Corp (DBA FeatureBase). All rights reserved.
+package keys
+
+// Index represents the name of a Featurebase index.
+type Index string
+
+// Field represents the name of a Featurebase field. It
+// is only meaningful within the context of a parent index.
+type Field string
+
+// View represents the name of a Featurebase view. It is
+// only meaningful within the context of a parent field.
+type View string
+
+// Shard represents the numeric shard ID of a shard. A shard
+// is specific to an index, but *not* specific to a field or
+// view.
+type Shard uint64
+
+// Fragment represents the full identifier of a Featurebase
+// fragment.
+type Fragment struct {
+	Index
+	Field
+	View
+	Shard
+}
+
+// Shards represents an unsorted list of shards.
+type Shards map[Shard]struct{}
+
+// ViewContents represents the set of shards a given view contains.
+type ViewContents Shards
+
+// helper function to protect us against the day when we need to track
+// more than this inside a ViewContents.
+func (v ViewContents) Shards() Shards {
+	return Shards(v)
+}
+
+// FieldContents represents the ViewContents for the views in a given field.
+type FieldContents map[View]ViewContents
+
+// IndexContents represents the FieldContents for the fields in a given index.
+type IndexContents map[Field]FieldContents
+
+// DBContents represents the IndexContents for the indexes in a DB.
+type DBContents map[Index]IndexContents