@arkiv-network/sdk 0.8.1-dev.1 → 0.9.0-next.2

package/src/query/selection.ts

@@ -1,85 +1,246 @@
-import { validateAttributeName } from "../attr"
-import type { Entity } from "../types/entity"
+import {
+  type AnyColumn,
+  type ArkivValue,
+  type AttributeSchema,
+  type Attributes,
+  type ColumnsOf,
+  describeColumns,
+  lookupColumn,
+  SCHEMA_ATTRIBUTE,
+  type Schema,
+  SchemaMismatchError,
+  type StrValue,
+  type TypeTag,
+  type ValueOf,
+  validateAttributeName,
+} from "../schema"
+import type { Entity, EntityFields } from "../types/entity"
 import type { RpcSelect } from "../types/rpcSchema"
 
 /**
- * The entity fields a query can select. Each maps one-to-one onto a field of {@link Entity}.
- *
- * `attributes` takes a third form beyond `true`/`false`: a map of names, to fetch only those.
- */
-export type SelectionFields = {
-  key?: boolean
-  owner?: boolean
-  creator?: boolean
-  createdAt?: boolean
-  updatedAt?: boolean
-  expiresAt?: boolean
-  creationFlags?: boolean
-  contentType?: boolean
-  payload?: boolean
-  /** Attribute names and types, without their values. */
-  attributeSchema?: boolean
-  /** `true` for every attribute, or a map of names for a subset. */
-  attributes?: boolean | Readonly<Record<string, boolean>>
+ * The entity fields a row can carry. Each is `$`-prefixed, like the system attributes `where`
+ * filters on: an attribute name cannot start with `$`, so no attribute can collide with one.
+ */
+export const SYSTEM_FIELDS = [
+  "$key",
+  "$owner",
+  "$creator",
+  "$createdAt",
+  "$updatedAt",
+  "$expiresAt",
+  "$creationFlags",
+] as const
+
+/** The name of an entity field a row carries alongside its attributes. */
+export type SystemField = (typeof SYSTEM_FIELDS)[number]
+
+/** The {@link Entity} property a system field reads. */
+type EntityField<F extends SystemField> = F extends `$${infer N extends keyof EntityFields}`
+  ? N
+  : never
+
+/**
+ * The keys a selection gives a fixed meaning: the entity fields, plus `$attributes` and
+ * `$attributeSchema`, which read an entity's attributes as a whole. Any key without a `$` names an
+ * attribute.
+ */
+export type SelectionFields = { [K in SystemField]?: boolean } & {
+  /**
+   * Attribute names, types and indexing, without their values — a cheap way to find out what
+   * entities hold before fetching values that may be large. See {@link AttributeSchema}.
+   */
+  $attributeSchema?: boolean
+  /** Every attribute, as a map keyed by name. */
+  $attributes?: boolean
 }
 
-/** The selection keys, in the order they are written into the RPC `select` object. */
+/** The selection keys with a fixed meaning, in the order they are written into the RPC `select`. */
 const SELECTION_KEYS = [
-  "key",
-  "owner",
-  "creator",
-  "createdAt",
-  "updatedAt",
-  "expiresAt",
-  "creationFlags",
-  "contentType",
-  "payload",
-  "attributeSchema",
-  "attributes",
+  ...SYSTEM_FIELDS,
+  "$attributeSchema",
+  "$attributes",
 ] as const satisfies readonly (keyof SelectionFields)[]
 
+/** A selection key with a fixed meaning. */
+type SelectionKey = (typeof SELECTION_KEYS)[number]
+
 /**
- * Requires at least one property of `T` to be present.
- * `{}` is not assignable, which is how `select({})` is rejected at compile time.
+ * A selection: entity fields, `$attributes` / `$attributeSchema`, and attributes by name, each set
+ * to `true` to ask for it. The same selection means the same thing with or without a schema —
+ * naming one with `.from(...)` only types and checks the selected attributes, and the filter. A
+ * named schema also restricts the query to entities tagged with its name, and leaves the tag out of
+ * every row.
  */
-type AtLeastOne<T, K extends keyof T = keyof T> = {
-  [P in K]: Required<Pick<T, P>> & Partial<Omit<T, P>>
-}[K]
+export type Selection = Readonly<Record<string, boolean | undefined>>
+
+/** Argument accepted by `select()` — a {@link Selection}, or `"*"` for everything. */
+export type SelectArg = Selection | "*"
+
+/** Whether a selection value asks for the field: `true` does, `false` and `undefined` do not. */
+export type Selected<V> = V extends false | undefined ? false : true
 
 /**
- * A non-empty entity selection — the object form accepted by `select()`. At least one field must be
- * selected.
+ * What a column reads back as: a value of its type, or `undefined` too if the column is optional.
  */
-export type EntitySelection = AtLeastOne<SelectionFields>
-
-/** Argument accepted by `select()` — a non-empty {@link EntitySelection}, or `"*"` for everything. */
-export type SelectArg = EntitySelection | "*"
+export type ColumnValue<C> = C extends {
+  readonly type: infer T extends TypeTag
+  readonly isOptional: infer O
+}
+  ? ValueOf<T> | (true extends O ? undefined : never)
+  : never
 
-/** Whether a selection value asks for the field: `true`, or a non-empty map of attribute names. */
-type Selected<V> = V extends false | undefined ? false : true
+/**
+ * What a selected key reads back as: an entity field as the entity has it, the attributes as a
+ * whole, or one attribute — typed by its column through a schema, and any value or none without.
+ */
+type FieldValue<K, TSchema extends Schema | undefined> = K extends SystemField
+  ? NonNullable<Entity[EntityField<K>]>
+  : K extends "$attributes"
+    ? Attributes
+    : K extends "$attributeSchema"
+      ? AttributeSchema
+      : K extends `$${string}`
+        ? never
+        : TSchema extends Schema
+          ? K extends keyof ColumnsOf<TSchema>
+            ? ColumnValue<ColumnsOf<TSchema>[K]>
+            : never
+          : ArkivValue | undefined
 
 /**
- * The result of a selection `S`: an {@link Entity} narrowed to exactly the selected fields (each
- * non-`undefined`). The shape is flat — `select({ owner: true })` yields `{ owner: Hex }`, read as
- * `entity.owner`. Accessing an unselected field is a compile error.
+ * One result of selection `S`, through schema `TSchema` or without one: the selected entity fields
+ * and attributes side by side, flat. Through a schema each attribute is typed as its column
+ * declares; without one it is whatever value the entity holds, or `undefined`. Accessing an
+ * unselected field is a compile error.
  *
- * `toText()` / `toJson()` operate on the payload, so they appear only when `payload` was selected —
- * calling them otherwise would always throw.
+ * @example
+ * // select({ $key: true, title: true })               → { $key: Hex; title: ArkivValue | undefined }
+ * // select({ $key: true, title: true }).from(Posts)   → { $key: Hex; title: StrValue }
  */
-export type ProjectedEntity<S> = {
-  readonly [K in keyof S as Selected<S[K]> extends true ? K : never]: K extends keyof Entity
-    ? NonNullable<Entity[K]>
-    : never
-} & (S extends { payload: true } ? Pick<Entity, "toText" | "toJson"> : unknown)
+export type Row<S, TSchema extends Schema | undefined = undefined> = {
+  readonly [K in keyof S as Selected<S[K]> extends true ? K : never]: FieldValue<K, TSchema>
+}
 
-/** A selection of every field, used to type the result of `select()` / `select("*")`. */
-type AllSelected = { [K in (typeof SELECTION_KEYS)[number]]: true }
+/**
+ * What `select()` / `select("*")` selects without a schema: every entity field and every
+ * attribute. Not the `$attributeSchema`: its point is learning an entity's shape without fetching
+ * its values, so returning it next to every value would only add to the response. It is only
+ * returned when asked for by name.
+ */
+type AllSelected = { [K in SystemField | "$attributes"]: true }
 
-/** The projected entity type when everything is selected — every field, plus the methods. */
-export type FullEntity = ProjectedEntity<AllSelected>
+/**
+ * The result when everything is selected without a schema — every entity field, and every
+ * attribute as the `$attributes` map. Also what `getEntity(key)` returns.
+ */
+export type FullEntity = Row<AllSelected>
+
+/** The row type when everything is selected through a schema — every entity field and column. */
+export type FullRow<TSchema extends Schema> = Row<
+  { [K in SystemField | keyof ColumnsOf<TSchema>]: true },
+  TSchema
+>
+
+declare const dynamic: unique symbol
 
 /**
- * Converts a {@link SelectArg} into the RPC `select` object.
+ * The selection type of a builder whose selection is only known at runtime — `select(sel)` with
+ * `sel` typed {@link SelectArg} rather than written inline. Nothing about which fields will be
+ * present can be known statically, so results are typed with every field optional.
+ */
+export type DynamicSelection = { readonly [dynamic]: true }
+
+/**
+ * A result whose selection is only known at runtime: any entity field and any attribute may be
+ * absent, because nothing says statically which were selected.
+ */
+export type PartialRow<TSchema extends Schema | undefined = undefined> = {
+  readonly [K in SystemField]?: NonNullable<Entity[EntityField<K>]>
+} & {
+  readonly $attributes?: Attributes
+  readonly $attributeSchema?: AttributeSchema
+} & (TSchema extends Schema
+    ? { readonly [K in keyof ColumnsOf<TSchema>]?: ValueOf<ColumnsOf<TSchema>[K]["type"]> }
+    : { readonly [name: string]: ArkivValue | undefined })
+
+/**
+ * Whether which fields `S` selects is only known at runtime: a selection typed {@link SelectArg} or
+ * {@link Selection}, or one with a field typed `boolean` rather than `true` or `false`.
+ */
+type IsDynamic<S> = string extends keyof Exclude<S, "*">
+  ? true
+  : S extends "*"
+    ? false
+    : true extends {
+          [K in keyof S]: [S[K]] extends [boolean] ? (boolean extends S[K] ? true : false) : false
+        }[keyof S]
+      ? true
+      : false
+
+/**
+ * The selection type a query carries for the selection `select()` or `query()` was given: `"*"`
+ * for everything, {@link DynamicSelection} when the fields are only known at runtime, and the
+ * selection itself otherwise.
+ */
+export type SelectionOf<S> = [S] extends ["*"]
+  ? "*"
+  : IsDynamic<S> extends true
+    ? DynamicSelection
+    : S
+
+/**
+ * Rejects a selection that asks for nothing at compile time — `{}`, or every field `false`:
+ * `unknown` when `S` asks for something, or when that is only known at runtime, and an object no
+ * selection satisfies otherwise.
+ */
+export type NonEmptySelection<S> = SelectionOf<S> extends "*" | DynamicSelection
+  ? unknown
+  : [keyof { [K in keyof S as Selected<S[K]> extends true ? K : never]: true }] extends [never]
+    ? { "select() needs at least one field set to true": true }
+    : unknown
+
+/**
+ * Rejects a `$` key that is not an entity field, `$attributes` or `$attributeSchema` at compile
+ * time. An attribute name cannot start with `$`, so such a key can only be a typo: `unknown` when
+ * there is none, and an object naming the offenders, which no selection satisfies, otherwise.
+ */
+export type KnownSystemFields<S> = SelectionOf<S> extends "*" | DynamicSelection
+  ? unknown
+  : [Extract<Exclude<keyof S, SelectionKey>, `$${string}`>] extends [never]
+    ? unknown
+    : {
+        "selected names that are not entity fields": Extract<
+          Exclude<keyof S, SelectionKey>,
+          `$${string}`
+        >
+      }
+
+/** What a query returns per result — a flat row, typed by the schema when there is one. */
+export type ResultOf<
+  TSelection,
+  TSchema extends Schema | undefined,
+> = TSelection extends DynamicSelection
+  ? PartialRow<TSchema>
+  : TSelection extends "*"
+    ? TSchema extends Schema
+      ? FullRow<TSchema>
+      : FullEntity
+    : Row<TSelection, TSchema>
+
+/**
+ * The keys of a selection that mean nothing through `TSchema` — neither an entity field,
+ * `$attributes` / `$attributeSchema`, nor a column. None for a star or a selection only known at
+ * runtime, which `from()` checks when it runs instead.
+ */
+export type UnknownSelection<TSelection, TSchema extends Schema> = TSelection extends
+  | "*"
+  | DynamicSelection
+  ? never
+  : Exclude<keyof TSelection, SelectionKey | keyof ColumnsOf<TSchema>>
+
+/**
+ * Converts a selection into the RPC `select` object — the same request {@link projectSelection}
+ * makes without a schema.
  *
  * Every field is opt-in — anything not explicitly selected is sent as `false`, including the key.
  * Sending the full object rather than omitting the `false`s keeps what the SDK asked for legible in
@@ -87,42 +248,222 @@ export type FullEntity = ProjectedEntity<AllSelected>
  *
  * `undefined` or `"*"` selects everything.
  *
- * @throws If the selection asks for nothing.
+ * @throws If the selection asks for nothing, or names an attribute outside the name grammar.
  *
  * @example
- * toRpcSelect()                    // everything
- * toRpcSelect({ key: true })       // only the key
- * toRpcSelect({ attributes: { projectId: true } })  // one named attribute
+ * toRpcSelect()                                     // everything
+ * toRpcSelect({ $key: true })                       // only the key
+ * toRpcSelect({ $key: true, projectId: true })      // the key and one attribute
  */
 export function toRpcSelect(selection?: SelectArg): RpcSelect {
+  return projectSelection(selection).select
+}
+
+/**
+ * A frozen copy of a selection, so that editing the object passed to `select()` afterwards cannot
+ * change what the builder sends.
+ */
+export function snapshotSelection<S extends SelectArg | undefined>(selection: S): S {
+  if (typeof selection !== "object" || selection === null) return selection
+  return Object.freeze({ ...selection }) as S
+}
+
+/**
+ * A selection resolved, through a schema or without one: what to ask the node for, and how to lay
+ * the answer out.
+ */
+export type Projection = {
+  readonly select: RpcSelect
+  /** The entity fields each row carries. */
+  readonly fields: readonly SystemField[]
+  /**
+   * The attributes each row carries as fields of their own, by name — each with its column
+   * through a schema, which the value is checked against, and `undefined` without one.
+   */
+  readonly columns: readonly (readonly [name: string, column: AnyColumn | undefined])[]
+  /** Whether each row carries the `$attributes` map. */
+  readonly attributes: boolean
+  /** Whether each row carries the `$attributeSchema`. */
+  readonly attributeSchema: boolean
+  /** The tag each entity must carry, for a named schema. Checked, never part of the row. */
+  readonly tag: StrValue | undefined
+}
+
+/**
+ * Resolves a selection, through a schema or without one. A key that does not start with `$` names
+ * an attribute — through a schema, it must be a column.
+ *
+ * `undefined` or `"*"` selects every entity field and, through a schema, every column; without one,
+ * every attribute as the `$attributes` map. The `$attributeSchema` is only selected by name.
+ *
+ * Attributes are fetched by name where possible, so the ones a row does not carry stay on the node.
+ * A named schema's tag is fetched too, so each entity can be checked against it.
+ *
+ * @throws If the selection asks for nothing, names a `$` key that is not an entity field, names an
+ * attribute outside the name grammar, or — through a schema — names an attribute that is not a
+ * column.
+ */
+export function projectSelection(selection?: SelectArg, schema?: Schema): Projection {
+  const fields: SystemField[] = []
+  const columns: [string, AnyColumn | undefined][] = []
+  let attributes = false
+  let attributeSchema = false
+
   if (selection === undefined || selection === "*") {
-    return Object.fromEntries(SELECTION_KEYS.map((field) => [field, true])) as RpcSelect
+    fields.push(...SYSTEM_FIELDS)
+    if (schema === undefined) {
+      attributes = true
+    } else {
+      columns.push(...Object.entries(schema.columns))
+    }
+  } else {
+    if (typeof selection !== "object" || selection === null || Array.isArray(selection)) {
+      throw new TypeError('select() takes "*" or an object of fields set to true')
+    }
+    for (const [name, wanted] of Object.entries(selection)) {
+      if (typeof wanted !== "boolean" && wanted !== undefined) {
+        throw new Error(
+          name === "$attributes"
+            ? 'select() takes true or false for "$attributes", which reads every attribute. To ' +
+                "read some of them, select each by name: select({ title: true, body: true })."
+            : `select() takes true or false for "${name}", got ${typeof wanted}.`,
+        )
+      }
+      const fixed = (SELECTION_KEYS as readonly string[]).includes(name)
+      if (!fixed && name.startsWith("$")) {
+        throw new Error(
+          `select() names "${name}", which is not an entity field. The entity fields are ` +
+            `${SYSTEM_FIELDS.join(", ")}, and $attributes and $attributeSchema read the ` +
+            "attributes as a whole.",
+        )
+      }
+      const column = fixed || schema === undefined ? undefined : lookupColumn(schema, name)
+      if (!fixed) {
+        if (schema !== undefined && column === undefined) {
+          throw new Error(
+            `select() names "${name}", which is not a column of the schema. Its columns are ` +
+              `${describeColumns(schema)}.`,
+          )
+        }
+        validateAttributeName(name)
+      }
+      if (!wanted) continue
+      if (name === "$attributes") attributes = true
+      else if (name === "$attributeSchema") attributeSchema = true
+      else if (fixed) fields.push(name as SystemField)
+      else columns.push([name, column])
+    }
+    // Rejects both `{}` and a selection whose fields are all explicitly `false` — the type system
+    // permits `select({ $key: false })`, and the node would answer it with a page of empty objects.
+    if (fields.length === 0 && columns.length === 0 && !attributes && !attributeSchema) {
+      throw nothingSelected()
+    }
   }
 
   const select: RpcSelect = {}
-  let any = false
-  for (const field of SELECTION_KEYS) {
-    const value = selection[field]
-    if (field === "attributes" && typeof value === "object" && value !== null) {
-      // A named subset. An empty map asks for no attributes at all, which is what `false` means.
-      const names = Object.entries(value).filter(([, wanted]) => wanted)
-      // Checked rather than forwarded: a name outside the grammar cannot exist on any entity, so
-      // asking for one is a typo that would otherwise come back as a silently absent attribute.
-      for (const [name] of names) validateAttributeName(name)
-      select.attributes = names.length > 0 ? Object.fromEntries(names) : false
-      any ||= names.length > 0
-      continue
+  for (const field of SYSTEM_FIELDS) select[entityField(field)] = fields.includes(field)
+  select.attributeSchema = attributeSchema
+  if (attributes) {
+    select.attributes = true
+  } else {
+    const names = new Set(columns.map(([name]) => name))
+    if (schema?.tag !== undefined) names.add(SCHEMA_ATTRIBUTE)
+    select.attributes =
+      names.size > 0 ? Object.fromEntries([...names].map((n) => [n, true])) : false
+  }
+  return { select, fields, columns, attributes, attributeSchema, tag: schema?.tag }
+}
+
+/**
+ * Lays an entity out as a row of `projection` — checking it against the schema, when there is one.
+ *
+ * @throws {SchemaMismatchError} If a named schema's entity is not tagged with its name, or the
+ * entity lacks a selected required column or holds one with a type other than the schema's — it
+ * was not written through this schema, or was patched since.
+ */
+export function toRow(entity: Entity, projection: Projection): Record<string, unknown> {
+  const subject = entity.key === undefined ? "the entity" : `entity ${entity.key}`
+
+  const { tag } = projection
+  if (tag !== undefined) {
+    const found = attributeOf(entity, SCHEMA_ATTRIBUTE)
+    if (found?.type !== "str" || found.value !== tag.value) {
+      throw new SchemaMismatchError(
+        SCHEMA_ATTRIBUTE,
+        `${subject} is ${describeTag(found)}, not ${JSON.stringify(tag.value)}, so it was not ` +
+          "written through this schema",
+      )
     }
-    select[field] = value === true
-    any ||= value === true
   }
 
-  // Rejects both `{}` and a selection whose fields are all explicitly `false` — the type system
-  // permits `select({ key: false })`, and the node would answer it with a page of empty objects.
-  if (!any) {
-    throw new Error(
-      'select() requires at least one field to be selected. Pass select() or select("*") to select everything.',
-    )
+  const row: Record<string, unknown> = {}
+  for (const field of projection.fields) row[field] = entity[entityField(field)]
+
+  for (const [name, column] of projection.columns) {
+    const value = attributeOf(entity, name)
+    if (column !== undefined) {
+      if (value === undefined) {
+        if (!column.isOptional) {
+          throw new SchemaMismatchError(
+            name,
+            `${subject} has no value for this required ${column.type} column, so it does not ` +
+              "match the schema. Declare the column .optional() if entities may leave it unset",
+          )
+        }
+      } else if (value.type !== column.type) {
+        throw new SchemaMismatchError(
+          name,
+          `${subject} holds a ${value.type}, not the ${column.type} the schema declares`,
+        )
+      }
+    }
+    row[name] = value
   }
-  return select
+
+  if (projection.attributes) {
+    row.$attributes = withoutTag(entity.attributes ?? {}, tag)
+  }
+  if (projection.attributeSchema) {
+    row.$attributeSchema = withoutTag(entity.attributeSchema ?? {}, tag)
+  }
+  return row
+}
+
+/** The {@link Entity} property, and RPC `select` key, a system field reads: its name without `$`. */
+function entityField<F extends SystemField>(field: F): EntityField<F> {
+  return field.slice(1) as EntityField<F>
+}
+
+/**
+ * A copy of `record` without a named schema's tag: the tag is how a query finds the schema's
+ * entities, not one of their attributes, so a row never carries it — and a map read back from a
+ * row drops into a write without sending the reserved name.
+ */
+function withoutTag<T>(record: Readonly<Record<string, T>>, tag: StrValue | undefined) {
+  if (tag === undefined || !Object.hasOwn(record, SCHEMA_ATTRIBUTE)) return record
+  const { [SCHEMA_ATTRIBUTE]: _tag, ...rest } = record
+  return rest
+}
+
+/**
+ * The entity's attribute `name`, or `undefined` if it has none. An own-property read: a column may
+ * be named `constructor` or `toString`, and an entity that leaves it unset must not find the
+ * inherited one instead.
+ */
+function attributeOf(entity: Entity, name: string): ArkivValue | undefined {
+  const { attributes } = entity
+  return attributes !== undefined && Object.hasOwn(attributes, name) ? attributes[name] : undefined
+}
+
+/** How an entity's schema tag reads in a mismatch — whatever type another writer gave it. */
+function describeTag(found: ArkivValue | undefined): string {
+  if (found === undefined) return "not tagged with a schema"
+  if (found.type === "str") return `tagged ${JSON.stringify(found.value)}`
+  return `tagged with a value of type ${found.type}`
+}
+
+function nothingSelected(): Error {
+  return new Error(
+    'select() requires at least one field to be selected. Pass select() or select("*") to select everything.',
+  )
 }