@sixb/core 0.0.1

package/src/edits/recorder.ts

@@ -0,0 +1,312 @@
+import { createHash } from "node:crypto"
+import type { ObjectLink, ValueType } from "../ontology"
+import { OntologyValidationError } from "../ontology/errors"
+import type { ObjectTypeWithPropertyTokens } from "../ontology/tokens"
+import { assertRequiredProperties } from "../ontology/validation"
+import { EditBatchError } from "./errors"
+import {
+  assertPrimaryPropertyNotUpdated,
+  getPrimaryProperty,
+  normalizeEditablePropertyIds,
+  normalizeLinkEditProperties,
+  normalizeObjectEditProperties,
+} from "./properties"
+import type {
+  EditBatch,
+  EditObjectHandle,
+  EditObjectProperties,
+  EditObjectRef,
+  EditOperation,
+  RecordEditsContext,
+  RecordEditsHandler,
+  RecordEditsOptions,
+} from "./types"
+
+export type { RecordEditsHandler, RecordEditsOptions } from "./types"
+
+const EMPTY_VALUE_TYPES = new Map<string, ValueType>()
+
+type RuntimeEditRecorder = {
+  readonly objects: (objectType: ObjectTypeWithPropertyTokens) => unknown
+  toEditBatch(): EditBatch
+}
+
+export async function recordEdits(
+  options: RecordEditsOptions,
+  handler: RecordEditsHandler
+): Promise<EditBatch> {
+  const recorder = createEditRecorder(options)
+  await handler({ objects: recorder.objects } as RecordEditsContext)
+  return recorder.toEditBatch()
+}
+
+function createEditRecorder(options: RecordEditsOptions): RuntimeEditRecorder {
+  if (!options.runId.trim()) {
+    throw new EditBatchError("[Sixb] recordEdits requires a non-empty runId.")
+  }
+
+  const operations: EditOperation[] = []
+  const valueTypesById = options.valueTypesById ?? EMPTY_VALUE_TYPES
+
+  function objects(objectType: ObjectTypeWithPropertyTokens) {
+    return {
+      byId(primaryId: string) {
+        return createObjectHandle(objectType, createRef(objectType.id, primaryId))
+      },
+
+      create(properties: unknown) {
+        const operationPath = String(operations.length)
+        const primaryProperty = getPrimaryProperty(objectType)
+        const rawProperties = assertRecord(properties, `${objectType.id}.create.properties`)
+        const primaryValue =
+          rawProperties[primaryProperty.id] ??
+          generatePrimaryId({
+            runId: options.runId,
+            operationPath,
+            objectTypeId: objectType.id,
+          })
+
+        if (typeof primaryValue !== "string" || !primaryValue.trim()) {
+          throw new EditBatchError(
+            `[Sixb] EditBatch create '${objectType.id}' primary property '${primaryProperty.id}' must be a non-empty string.`
+          )
+        }
+
+        const normalizedProperties = normalizeObjectEditProperties({
+          objectType,
+          properties: {
+            ...rawProperties,
+            [primaryProperty.id]: primaryValue,
+          },
+          valueTypesById,
+          path: `${objectType.id}.create`,
+        })
+        assertRequiredProperties(objectType, normalizedProperties)
+
+        operations.push({
+          kind: "object.create",
+          objectTypeId: objectType.id,
+          primaryId: primaryValue,
+          properties: withoutPrimaryProperty(normalizedProperties, primaryProperty.id),
+        })
+        return createObjectHandle(objectType, {
+          objectTypeId: objectType.id,
+          primaryId: primaryValue,
+        })
+      },
+    }
+  }
+
+  function toEditBatch(): EditBatch {
+    return { operations: [...operations] }
+  }
+
+  function createObjectHandle(
+    objectType: ObjectTypeWithPropertyTokens,
+    ref: EditObjectRef
+  ): EditObjectHandle<ObjectTypeWithPropertyTokens> {
+    const handle = {
+      objectTypeId: ref.objectTypeId,
+      primaryId: ref.primaryId,
+    }
+
+    Object.defineProperties(handle, {
+      objectType: {
+        value: objectType,
+      },
+      update: {
+        value(properties: Readonly<Record<string, unknown>>) {
+          const normalizedProperties = normalizeObjectEditProperties({
+            objectType,
+            properties: assertRecord(properties, `${objectType.id}.update.properties`),
+            valueTypesById,
+            path: `${objectType.id}.update`,
+          })
+          assertPrimaryPropertyNotUpdated(objectType, normalizedProperties)
+          // An empty patch resolves to a null override and commits as `unchanged`, so a handler
+          // that built its update conditionally would report a successful run that wrote nothing.
+          if (Object.keys(normalizedProperties).length === 0) {
+            throw new EditBatchError(
+              `[Sixb] EditBatch update '${objectType.id}:${ref.primaryId}' must set at least one property.`
+            )
+          }
+
+          operations.push({
+            kind: "object.update",
+            objectTypeId: ref.objectTypeId,
+            primaryId: ref.primaryId,
+            properties: normalizedProperties,
+          })
+        },
+      },
+      unset: {
+        value(...propertyIds: readonly unknown[]) {
+          operations.push({
+            kind: "object.unset",
+            objectTypeId: ref.objectTypeId,
+            primaryId: ref.primaryId,
+            propertyIds: normalizeEditablePropertyIds({
+              objectType,
+              propertyIds,
+              operation: "unset",
+            }),
+          })
+        },
+      },
+      reset: {
+        value(...propertyIds: readonly unknown[]) {
+          operations.push({
+            kind: "object.reset",
+            objectTypeId: ref.objectTypeId,
+            primaryId: ref.primaryId,
+            propertyIds: normalizeEditablePropertyIds({
+              objectType,
+              propertyIds,
+              operation: "reset",
+            }),
+          })
+        },
+      },
+      delete: {
+        value() {
+          operations.push({
+            kind: "object.delete",
+            objectTypeId: ref.objectTypeId,
+            primaryId: ref.primaryId,
+          })
+        },
+      },
+      restore: {
+        value() {
+          operations.push({
+            kind: "object.restore",
+            objectTypeId: ref.objectTypeId,
+            primaryId: ref.primaryId,
+          })
+        },
+      },
+      link: {
+        value(
+          link: { objectTypeId: string; id: string; link: ObjectLink },
+          target: EditObjectRef,
+          linkOptions?: { readonly properties?: Readonly<Record<string, unknown>> }
+        ) {
+          assertLinkTokenSource(ref, link)
+
+          const properties =
+            linkOptions?.properties === undefined
+              ? undefined
+              : normalizeLinkEditProperties({
+                  sourceObjectTypeId: ref.objectTypeId,
+                  linkId: link.id,
+                  linkDefinition: link.link,
+                  properties: linkOptions.properties,
+                  valueTypesById,
+                })
+
+          operations.push({
+            kind: "link.upsert",
+            source: toPlainRef(ref),
+            linkId: link.id,
+            target: toPlainRef(target),
+            ...(properties !== undefined ? { properties } : {}),
+          })
+        },
+      },
+      unlink: {
+        value(link: { objectTypeId: string; id: string; link: ObjectLink }, target: EditObjectRef) {
+          assertLinkTokenSource(ref, link)
+
+          operations.push({
+            kind: "link.delete",
+            source: toPlainRef(ref),
+            linkId: link.id,
+            target: toPlainRef(target),
+          })
+        },
+      },
+      resetLink: {
+        value(link: { objectTypeId: string; id: string; link: ObjectLink }, target: EditObjectRef) {
+          assertLinkTokenSource(ref, link)
+
+          operations.push({
+            kind: "link.reset",
+            source: toPlainRef(ref),
+            linkId: link.id,
+            target: toPlainRef(target),
+          })
+        },
+      },
+    })
+
+    return handle as EditObjectHandle<ObjectTypeWithPropertyTokens>
+  }
+
+  return {
+    objects,
+    toEditBatch,
+  }
+}
+
+function assertLinkTokenSource(
+  source: EditObjectRef,
+  link: { readonly objectTypeId: string; readonly id: string }
+): void {
+  if (source.objectTypeId !== link.objectTypeId) {
+    throw new OntologyValidationError(
+      `[Sixb] Link token ${link.objectTypeId}.${link.id} cannot be used with ${source.objectTypeId}`
+    )
+  }
+}
+
+function createRef<TObjectTypeId extends string>(
+  objectTypeId: TObjectTypeId,
+  primaryId: string
+): EditObjectRef<TObjectTypeId> {
+  return {
+    objectTypeId: assertNonEmptyString(objectTypeId, "objectTypeId") as TObjectTypeId,
+    primaryId: assertNonEmptyString(primaryId, `${objectTypeId}.primaryId`),
+  }
+}
+
+function generatePrimaryId(params: {
+  readonly runId: string
+  readonly operationPath: string
+  readonly objectTypeId: string
+}): string {
+  const hash = createHash("sha256")
+    .update(`${params.runId}:${params.operationPath}:${params.objectTypeId}`)
+    .digest("hex")
+    .slice(0, 24)
+  return `edit_${hash}`
+}
+
+/** Primary identity lives in the object ref; managed authority never stores it as a property. */
+function withoutPrimaryProperty(
+  properties: EditObjectProperties,
+  primaryPropertyId: string
+): EditObjectProperties {
+  const { [primaryPropertyId]: _primary, ...rest } = properties
+  return rest
+}
+
+function assertRecord(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new EditBatchError(`[Sixb] EditBatch ${label} must be an object.`)
+  }
+  return value as Record<string, unknown>
+}
+
+function assertNonEmptyString(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new EditBatchError(`[Sixb] EditBatch ${label} must be a non-empty string.`)
+  }
+  return value
+}
+
+function toPlainRef(ref: EditObjectRef): EditObjectRef {
+  return {
+    objectTypeId: ref.objectTypeId,
+    primaryId: ref.primaryId,
+  }
+}

package/src/edits/types.ts

@@ -0,0 +1,275 @@
+import type { JsonValue } from "../json"
+import type { ObjectRef, ObjectType, Property, ValueType } from "../ontology"
+import type { InferPropertyValue } from "../ontology/inference"
+import type { LinkToken, ObjectTypeWithPropertyTokens } from "../ontology/tokens"
+
+export interface EditObjectRef<TObjectTypeId extends string = string>
+  extends ObjectRef<TObjectTypeId> {}
+
+export interface TypedEditObjectRef<TObjectType extends ObjectType = ObjectType>
+  extends EditObjectRef<TObjectType["id"]> {}
+
+/** Authored property values, already normalized to JSON by the recorder. */
+export type EditObjectProperties = Readonly<Record<string, JsonValue>>
+
+export interface ObjectCreateEdit {
+  readonly kind: "object.create"
+  readonly objectTypeId: string
+  readonly primaryId: string
+  readonly properties: EditObjectProperties
+}
+
+export interface ObjectUpdateEdit {
+  readonly kind: "object.update"
+  readonly objectTypeId: string
+  readonly primaryId: string
+  readonly properties: EditObjectProperties
+}
+
+export interface ObjectUnsetEdit {
+  readonly kind: "object.unset"
+  readonly objectTypeId: string
+  readonly primaryId: string
+  readonly propertyIds: readonly string[]
+}
+
+export interface ObjectResetEdit {
+  readonly kind: "object.reset"
+  readonly objectTypeId: string
+  readonly primaryId: string
+  readonly propertyIds: readonly string[]
+}
+
+export interface ObjectDeleteEdit {
+  readonly kind: "object.delete"
+  readonly objectTypeId: string
+  readonly primaryId: string
+}
+
+export interface ObjectRestoreEdit {
+  readonly kind: "object.restore"
+  readonly objectTypeId: string
+  readonly primaryId: string
+}
+
+export interface LinkUpsertEdit {
+  readonly kind: "link.upsert"
+  readonly source: EditObjectRef
+  readonly linkId: string
+  readonly target: EditObjectRef
+  readonly properties?: EditObjectProperties
+}
+
+export interface LinkDeleteEdit {
+  readonly kind: "link.delete"
+  readonly source: EditObjectRef
+  readonly linkId: string
+  readonly target: EditObjectRef
+}
+
+export interface LinkResetEdit {
+  readonly kind: "link.reset"
+  readonly source: EditObjectRef
+  readonly linkId: string
+  readonly target: EditObjectRef
+}
+
+export type EditOperation =
+  | ObjectCreateEdit
+  | ObjectUpdateEdit
+  | ObjectUnsetEdit
+  | ObjectResetEdit
+  | ObjectDeleteEdit
+  | ObjectRestoreEdit
+  | LinkUpsertEdit
+  | LinkDeleteEdit
+  | LinkResetEdit
+
+export interface EditBatch {
+  readonly operations: readonly EditOperation[]
+}
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+type NonTelemetryProperty<TProperty extends Property> = TProperty extends { mode: "telemetry" }
+  ? never
+  : TProperty
+
+// Distributes over the property union directly: probing a derived type instead would collapse the
+// union and hand every id back, including primary and telemetry ones.
+type SettablePropertyId<TProperty extends Property> = TProperty extends { primary: true }
+  ? never
+  : TProperty extends { mode: "telemetry" }
+    ? never
+    : TProperty["id"]
+
+type CreatablePropertyId<TProperty extends Property> =
+  NonTelemetryProperty<TProperty> extends never ? never : TProperty["id"]
+
+/** Property ids an Action may set, unset, or reset — everything except primary and telemetry. */
+export type EditablePropertyId<TObjectType extends ObjectType> =
+  string extends TObjectType["properties"][number]["id"]
+    ? string
+    : SettablePropertyId<TObjectType["properties"][number]>
+
+type StaticPropertyMap<
+  TProperties extends readonly Property[],
+  TValueTypes extends readonly ValueType[],
+  TMode extends "create" | "update",
+> = string extends TProperties[number]["id"]
+  ? Record<string, unknown>
+  : Simplify<{
+      [TProp in TProperties[number] as TMode extends "create"
+        ? CreatablePropertyId<TProp>
+        : SettablePropertyId<TProp>]?: InferPropertyValue<TProp, TValueTypes>
+    }>
+
+export type EditCreateProperties<
+  TObjectType extends ObjectType,
+  TValueTypes extends readonly ValueType[] = [],
+> = StaticPropertyMap<TObjectType["properties"], TValueTypes, "create">
+
+export type EditUpdateProperties<
+  TObjectType extends ObjectType,
+  TValueTypes extends readonly ValueType[] = [],
+> = StaticPropertyMap<TObjectType["properties"], TValueTypes, "update">
+
+type LinkProperties<TLink extends { properties?: readonly Property[] }> = TLink extends {
+  properties: infer TProperties extends readonly Property[]
+}
+  ? TProperties
+  : []
+
+type LinkPropertyId<TProperty extends Property> =
+  NonTelemetryProperty<TProperty> extends never ? never : TProperty["id"]
+
+type RequiredLinkPropertyId<TProperty extends Property> = TProperty extends { required: true }
+  ? LinkPropertyId<TProperty>
+  : never
+
+type EditLinkProperties<
+  TLink extends { properties?: readonly Property[] },
+  TValueTypes extends readonly ValueType[],
+> = string extends LinkProperties<TLink>[number]["id"]
+  ? Record<string, unknown>
+  : Simplify<
+      {
+        [TProp in LinkProperties<TLink>[number] as RequiredLinkPropertyId<TProp>]: InferPropertyValue<
+          TProp,
+          TValueTypes
+        >
+      } & {
+        [TProp in LinkProperties<TLink>[number] as TProp extends { required: true }
+          ? never
+          : LinkPropertyId<TProp>]?: InferPropertyValue<TProp, TValueTypes>
+      }
+    >
+
+type RequiredLinkPropertyIds<TLink extends { properties?: readonly Property[] }> =
+  LinkProperties<TLink>[number] extends infer TProperty extends Property
+    ? RequiredLinkPropertyId<TProperty>
+    : never
+
+type HasLinkProperties<TLink extends { properties?: readonly Property[] }> =
+  LinkProperties<TLink> extends [] ? false : true
+
+type HasRequiredLinkProperties<TLink extends { properties?: readonly Property[] }> = [
+  RequiredLinkPropertyIds<TLink>,
+] extends [never]
+  ? false
+  : true
+
+type ResolveTargetObjectTypeId<TTargetObjectTypeId> =
+  TTargetObjectTypeId extends readonly (infer TTargetId extends string)[]
+    ? TTargetId
+    : TTargetObjectTypeId extends string
+      ? TTargetObjectTypeId
+      : never
+
+type EditLinkTargetRef<TLinkToken extends LinkToken<string, string, string | readonly string[]>> =
+  string extends TLinkToken["id"]
+    ? EditObjectRef<string>
+    : EditObjectRef<ResolveTargetObjectTypeId<TLinkToken["targetObjectTypeId"]>>
+
+type EditLinkOptionsArg<
+  TLinkToken extends LinkToken<string, string, string | readonly string[]>,
+  TValueTypes extends readonly ValueType[],
+> = string extends TLinkToken["id"]
+  ? [options?: { readonly properties?: Readonly<Record<string, unknown>> }]
+  : HasLinkProperties<TLinkToken["link"]> extends false
+    ? [options?: { readonly properties?: never }]
+    : HasRequiredLinkProperties<TLinkToken["link"]> extends true
+      ? [
+          options: {
+            readonly properties: EditLinkProperties<TLinkToken["link"], TValueTypes>
+          },
+        ]
+      : [
+          options?: {
+            readonly properties?: EditLinkProperties<TLinkToken["link"], TValueTypes>
+          },
+        ]
+
+export interface RecordEditsOptions {
+  readonly runId: string
+  readonly valueTypesById?: ReadonlyMap<string, ValueType>
+}
+
+export interface RecordEditsContext<TValueTypes extends readonly ValueType[] = []> {
+  objects<const TObjectType extends ObjectTypeWithPropertyTokens>(
+    objectType: TObjectType
+  ): EditObjectSetRecorder<TObjectType, TValueTypes>
+}
+
+export type RecordEditsHandlerResult = ReturnType<() => void>
+
+export type RecordEditsHandlerReturn = RecordEditsHandlerResult | Promise<RecordEditsHandlerResult>
+
+export type RecordEditsHandler<
+  TValueTypes extends readonly ValueType[] = [],
+  TResult extends RecordEditsHandlerReturn = RecordEditsHandlerReturn,
+> = (ctx: RecordEditsContext<TValueTypes>) => TResult
+
+export interface EditObjectSetRecorder<
+  TObjectType extends ObjectType,
+  TValueTypes extends readonly ValueType[] = [],
+> {
+  byId(primaryId: string): EditObjectHandle<TObjectType, TValueTypes>
+
+  create(
+    properties: EditCreateProperties<TObjectType, TValueTypes>
+  ): EditObjectHandle<TObjectType, TValueTypes>
+}
+
+export interface EditObjectHandle<
+  TObjectType extends ObjectType = ObjectType,
+  TValueTypes extends readonly ValueType[] = [],
+> extends TypedEditObjectRef<TObjectType> {
+  update(properties: EditUpdateProperties<TObjectType, TValueTypes>): void
+
+  /** Clears managed values, leaving the property absent from managed authority. */
+  unset(...propertyIds: readonly EditablePropertyId<TObjectType>[]): void
+
+  /** Drops managed authority so source authority becomes visible again. */
+  reset(...propertyIds: readonly EditablePropertyId<TObjectType>[]): void
+
+  delete(): void
+
+  restore(): void
+
+  link<const TLinkToken extends LinkToken<TObjectType["id"], string, string | readonly string[]>>(
+    link: TLinkToken,
+    target: EditLinkTargetRef<TLinkToken>,
+    ...options: EditLinkOptionsArg<TLinkToken, TValueTypes>
+  ): void
+
+  unlink<const TLinkToken extends LinkToken<TObjectType["id"], string, string | readonly string[]>>(
+    link: TLinkToken,
+    target: EditLinkTargetRef<TLinkToken>
+  ): void
+
+  /** Drops managed link authority so source link authority becomes visible again. */
+  resetLink<
+    const TLinkToken extends LinkToken<TObjectType["id"], string, string | readonly string[]>,
+  >(link: TLinkToken, target: EditLinkTargetRef<TLinkToken>): void
+}