@contember/bindx 0.1.0

package/src/handles/PlaceholderHandle.ts

@@ -0,0 +1,321 @@
+import type { ActionDispatcher } from '../core/ActionDispatcher.js'
+import type { SnapshotStore } from '../store/SnapshotStore.js'
+import { generatePlaceholderId } from '../store/SnapshotStore.js'
+import {
+	FIELD_REF_META,
+	type EntityRef,
+	type SelectedEntityFields,
+	type FieldRefMeta,
+	type Unsubscribe,
+} from './types.js'
+import type { ErrorInput, FieldError } from '../errors/types.js'
+import type {
+	EventTypeMap,
+	AfterEventTypes,
+	BeforeEventTypes,
+	EventListener,
+	Interceptor,
+	EntityPersistedEvent,
+	EntityPersistingEvent,
+} from '../events/types.js'
+import { createAliasProxy } from './proxyFactory.js'
+
+/**
+ * PlaceholderHandle provides access to a placeholder entity (for creating new entities).
+ * Implements EntityRef interface with a placeholder ID.
+ * Reads/writes from placeholderData in the relation state.
+ *
+ * @typeParam TEntity - The full entity type
+ * @typeParam TSelected - The selected subset of fields
+ */
+export class PlaceholderHandle<TEntity extends object = object, TSelected = TEntity>
+	implements EntityRef<TEntity, TSelected>
+{
+	/** Runtime brand symbols for validation */
+	readonly __brands?: Set<symbol>
+
+	/** Type brand for schema - placeholder at runtime */
+	declare readonly __schema: Record<string, object>
+
+	/** Placeholder ID for this handle */
+	private readonly placeholderId: string
+
+	// $ aliases - handled by proxy at runtime, declared for TypeScript
+	declare readonly $fields: SelectedEntityFields<TEntity, TSelected>
+	declare readonly $data: TSelected | null
+	declare readonly $isDirty: boolean
+	declare readonly $persistedId: null
+	declare readonly $isNew: boolean
+	declare readonly $errors: readonly FieldError[]
+	declare readonly $hasError: boolean
+	declare $addError: (error: ErrorInput) => void
+	declare $clearErrors: () => void
+	declare $clearAllErrors: () => void
+	declare $on: <E extends AfterEventTypes>(eventType: E, listener: EventListener<EventTypeMap[E]>) => Unsubscribe
+	declare $intercept: <E extends BeforeEventTypes>(eventType: E, interceptor: Interceptor<EventTypeMap[E]>) => Unsubscribe
+	declare $onPersisted: (listener: EventListener<EntityPersistedEvent>) => Unsubscribe
+	declare $interceptPersisting: (interceptor: Interceptor<EntityPersistingEvent>) => Unsubscribe
+
+	private constructor(
+		private readonly parentEntityType: string,
+		private readonly parentEntityId: string,
+		private readonly fieldName: string,
+		private readonly targetType: string,
+		private readonly store: SnapshotStore,
+		private readonly dispatcher: ActionDispatcher,
+		brands?: Set<symbol>,
+	) {
+		this.__brands = brands
+		this.placeholderId = generatePlaceholderId()
+	}
+
+	static create<TEntity extends object = object, TSelected = TEntity>(
+		parentEntityType: string,
+		parentEntityId: string,
+		fieldName: string,
+		targetType: string,
+		store: SnapshotStore,
+		dispatcher: ActionDispatcher,
+		brands?: Set<symbol>,
+	): PlaceholderHandle<TEntity, TSelected> {
+		return createAliasProxy(new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, brands))
+	}
+
+	/**
+	 * Gets the placeholder ID.
+	 */
+	get id(): string {
+		return this.placeholderId
+	}
+
+	/**
+	 * Gets placeholder data from the relation state.
+	 */
+	get data(): TSelected | null {
+		const relation = this.store.getRelation(
+			this.parentEntityType,
+			this.parentEntityId,
+			this.fieldName,
+		)
+		if (!relation || Object.keys(relation.placeholderData).length === 0) {
+			return null
+		}
+		return relation.placeholderData as TSelected
+	}
+
+	/**
+	 * Placeholder is dirty if it has any data.
+	 */
+	get isDirty(): boolean {
+		const relation = this.store.getRelation(
+			this.parentEntityType,
+			this.parentEntityId,
+			this.fieldName,
+		)
+		return relation ? Object.keys(relation.placeholderData).length > 0 : false
+	}
+
+	/**
+	 * Placeholder entities are always new (not yet persisted).
+	 */
+	get persistedId(): null {
+		return null
+	}
+
+	/**
+	 * Placeholder entities are always new.
+	 */
+	get isNew(): boolean {
+		return true
+	}
+
+	/**
+	 * Gets field accessors that read/write placeholder data.
+	 */
+	get fields(): SelectedEntityFields<TEntity, TSelected> {
+		return new Proxy({} as SelectedEntityFields<TEntity, TSelected>, {
+			get: (_, fieldName: string) => {
+				return this.createPlaceholderFieldHandle(fieldName)
+			},
+		})
+	}
+
+	/**
+	 * Creates a field handle for placeholder data.
+	 */
+	private createPlaceholderFieldHandle(fieldName: string): unknown {
+		const self = this
+
+		return {
+			get [FIELD_REF_META](): FieldRefMeta {
+				return {
+					entityType: self.targetType,
+					entityId: self.placeholderId,
+					path: [fieldName],
+					fieldName,
+					isArray: false,
+					isRelation: false,
+				}
+			},
+			get value(): unknown {
+				const relation = self.store.getRelation(
+					self.parentEntityType,
+					self.parentEntityId,
+					self.fieldName,
+				)
+				return relation?.placeholderData[fieldName] ?? null
+			},
+			get serverValue(): unknown {
+				return null
+			},
+			get isDirty(): boolean {
+				const relation = self.store.getRelation(
+					self.parentEntityType,
+					self.parentEntityId,
+					self.fieldName,
+				)
+				return fieldName in (relation?.placeholderData ?? {})
+			},
+			setValue: (value: unknown): void => {
+				self.dispatcher.dispatch({
+					type: 'SET_PLACEHOLDER_DATA',
+					entityType: self.parentEntityType,
+					entityId: self.parentEntityId,
+					fieldName: self.fieldName,
+					fieldPath: [fieldName],
+					value,
+				})
+			},
+			get inputProps() {
+				const getValue = () => {
+					const relation = self.store.getRelation(
+						self.parentEntityType,
+						self.parentEntityId,
+						self.fieldName,
+					)
+					return relation?.placeholderData[fieldName] ?? null
+				}
+				const setValue = (value: unknown) => {
+					self.dispatcher.dispatch({
+						type: 'SET_PLACEHOLDER_DATA',
+						entityType: self.parentEntityType,
+						entityId: self.parentEntityId,
+						fieldName: self.fieldName,
+						fieldPath: [fieldName],
+						value,
+					})
+				}
+				return {
+					get value() {
+						return getValue()
+					},
+					setValue,
+					onChange: setValue,
+				}
+			},
+			path: [fieldName],
+			fieldName,
+			// Error properties for FieldRef interface
+			get errors(): readonly FieldError[] {
+				return []
+			},
+			get hasError(): boolean {
+				return false
+			},
+			addError(_error: ErrorInput): void {
+				// Placeholder fields don't store errors
+			},
+			clearErrors(): void {
+				// Placeholder fields don't have errors to clear
+			},
+		}
+	}
+
+	/**
+	 * Type brand for EntityRef compatibility.
+	 */
+	get __entityType(): TEntity {
+		return undefined as unknown as TEntity
+	}
+
+	/**
+	 * Entity name for type inference.
+	 */
+	get __entityName(): string {
+		return this.targetType
+	}
+
+	/**
+	 * Placeholder entities don't have persistent errors.
+	 * Returns empty array.
+	 */
+	get errors(): readonly FieldError[] {
+		return []
+	}
+
+	/**
+	 * Placeholder entities don't have errors.
+	 */
+	get hasError(): boolean {
+		return false
+	}
+
+	/**
+	 * No-op for placeholder entities.
+	 */
+	addError(_error: ErrorInput): void {
+		// Placeholder entities don't store errors
+	}
+
+	/**
+	 * No-op for placeholder entities.
+	 */
+	clearErrors(): void {
+		// Placeholder entities don't have errors to clear
+	}
+
+	/**
+	 * No-op for placeholder entities.
+	 */
+	clearAllErrors(): void {
+		// Placeholder entities don't have errors to clear
+	}
+
+	// ==================== Event Subscriptions ====================
+	// Placeholder entities don't fire events - these are no-ops that return dummy unsubscribe functions
+
+	/**
+	 * No-op for placeholder entities.
+	 */
+	on<E extends AfterEventTypes>(
+		_eventType: E,
+		_listener: EventListener<EventTypeMap[E]>,
+	): Unsubscribe {
+		return () => {}
+	}
+
+	/**
+	 * No-op for placeholder entities.
+	 */
+	intercept<E extends BeforeEventTypes>(
+		_eventType: E,
+		_interceptor: Interceptor<EventTypeMap[E]>,
+	): Unsubscribe {
+		return () => {}
+	}
+
+	/**
+	 * No-op for placeholder entities.
+	 */
+	onPersisted(_listener: EventListener<EntityPersistedEvent>): Unsubscribe {
+		return () => {}
+	}
+
+	/**
+	 * No-op for placeholder entities.
+	 */
+	interceptPersisting(_interceptor: Interceptor<EntityPersistingEvent>): Unsubscribe {
+		return () => {}
+	}
+
+}

package/src/handles/index.ts

@@ -0,0 +1,37 @@
+export { BaseHandle, EntityRelatedHandle } from './BaseHandle.js'
+export { FieldHandle } from './FieldHandle.js'
+export { EntityHandle } from './EntityHandle.js'
+export { HasOneHandle } from './HasOneHandle.js'
+export { PlaceholderHandle } from './PlaceholderHandle.js'
+export { HasManyListHandle } from './HasManyListHandle.js'
+export {
+	FIELD_REF_META,
+	type HasOneRelationState,
+	type EntityFields,
+	type SelectedEntityFields,
+	type SelectedEntityFieldsBase,
+	type ScalarKeys,
+	type HasManyKeys,
+	type HasOneKeys,
+	type FieldRefMeta,
+	type InputProps,
+	// Full types (for explicit selection - have .value, .length, etc.)
+	type FieldRef,
+	type HasManyRef,
+	type HasOneRef,
+	type HasOneAccessor,
+	type EntityRef,
+	type EntityAccessor,
+	// Base types (for implicit selection - no .value, .length, etc.)
+	type FieldRefBase,
+	type HasManyRefBase,
+	type HasOneRefBase,
+	type HasOneAccessorBase,
+	type EntityRefBase,
+	type EntityAccessorBase,
+	type Unsubscribe,
+	// Type extraction helpers
+	type ExtractHasOneEntityName,
+	type ExtractHasManyEntityName,
+	type ExtractRoleMap,
+} from './types.js'

package/src/handles/proxyFactory.ts

@@ -0,0 +1,218 @@
+/**
+ * Shared proxy factory for creating handle proxies with direct field access and $ aliasing.
+ *
+ * This module provides:
+ * 1. createHandleProxy - for EntityHandle/HasOneHandle with field access via proxy
+ * 2. createAliasProxy - for FieldHandle/HasManyListHandle/PlaceholderHandle with $ aliasing only
+ *
+ * The $ prefix convention allows handle properties to avoid collision with entity field names:
+ * - `entity.title` → field access (returns FieldHandle)
+ * - `entity.$isDirty` → handle property
+ */
+
+import { FIELD_REF_META } from './types.js'
+
+/**
+ * Shared base properties for entity-like handles (EntityHandle, HasOneHandle).
+ * Extracting a common set prevents bugs from inconsistent maintenance (e.g. missing `id`).
+ */
+const BASE_ENTITY_PROPERTIES: (string | symbol)[] = [
+	// Entity identity — id is always the entity ID, not a field handle
+	'id',
+	// Type brands (phantom types)
+	'__entityType', '__entityName', '__brands', '__schema',
+	// Symbol
+	FIELD_REF_META,
+	// Core internals shared by all entity-like handles
+	'entityType', 'entityId', 'store', 'dispatcher', 'schema',
+	'getEntityData', 'getServerData', 'assertNotDisposed', 'isDisposed',
+	'dispose', 'subscribe',
+]
+
+/**
+ * Known properties on EntityHandle that should NOT be treated as field access.
+ * Properties like `fields`, `data`, `errors` are NOT included - use $ prefix for those.
+ */
+export const ENTITY_HANDLE_PROPERTIES = new Set<string | symbol>([
+	...BASE_ENTITY_PROPERTIES,
+	// Entity-specific internals
+	'fieldHandleCache', 'relationHandleCache',
+	// Internal methods (unlikely to be field names)
+	'field', 'hasOne', 'hasMany', 'getSnapshot',
+	'reset', 'commit',
+	'getDirtyFields', 'getDirtyRelations',
+	// State properties (unlikely to be field names)
+	'serverData', 'isLoaded', 'isLoading', 'isError', 'error', 'isPersisting',
+])
+
+/**
+ * Known properties on HasOneHandle that should NOT be treated as field access.
+ * Properties like `fields`, `entity`, `errors`, `state` are NOT included - they require $ prefix.
+ */
+export const HAS_ONE_HANDLE_PROPERTIES = new Set<string | symbol>([
+	...BASE_ENTITY_PROPERTIES,
+	// HasOne-specific internals
+	'fieldName', 'targetType',
+	'entityHandleCache', 'placeholderCache', 'ensureRelatedEntitySnapshot', 'relatedId',
+	// Methods that are unlikely to be field names
+	'connect', 'disconnect', 'delete', 'reset',
+])
+
+/**
+ * All properties on FieldHandle (no field access proxy needed, just $ aliasing).
+ */
+export const FIELD_HANDLE_PROPERTIES = new Set<string | symbol>([
+	FIELD_REF_META,
+	// Core properties
+	'value', 'serverValue', 'isDirty', 'inputProps', 'errors', 'hasError',
+	'path', 'fieldName',
+	// Methods
+	'setValue', 'addError', 'clearErrors', 'onChange', 'onChanging', 'nested',
+	// Internal
+	'entityType', 'entityId', 'fieldPath', 'store', 'dispatcher',
+	'getEntityData', 'getServerData', 'assertNotDisposed', 'isDisposed',
+	'subscribe', 'dispose',
+])
+
+/**
+ * All properties on HasManyListHandle (no field access proxy needed, just $ aliasing).
+ */
+export const HAS_MANY_HANDLE_PROPERTIES = new Set<string | symbol>([
+	FIELD_REF_META,
+	// Type brands
+	'__entityType', '__brands',
+	// Core properties
+	'items', 'length', 'isDirty', 'errors', 'hasError',
+	// Methods
+	'map', 'add', 'remove', 'move', 'connect', 'disconnect', 'reset',
+	'getItemHandle', 'addError', 'clearErrors',
+	'onItemConnected', 'onItemDisconnected', 'interceptItemConnecting', 'interceptItemDisconnecting',
+	// Internal
+	'entityType', 'entityId', 'fieldName', 'itemType', 'store', 'dispatcher', 'schema',
+	'itemHandleCache', 'getEntityData', 'getServerData', 'assertNotDisposed', 'isDisposed',
+	'subscribe', 'dispose', 'ensureItemSnapshots',
+])
+
+/**
+ * All properties on PlaceholderHandle (no field access proxy needed, just $ aliasing).
+ */
+export const PLACEHOLDER_HANDLE_PROPERTIES = new Set<string | symbol>([
+	// Core properties
+	'id', 'data', 'isDirty', 'persistedId', 'isNew', 'fields', 'errors', 'hasError',
+	// Type brands
+	'__entityType', '__entityName', '__brands',
+	// Methods
+	'addError', 'clearErrors', 'clearAllErrors',
+	'on', 'intercept', 'onPersisted', 'interceptPersisting',
+	// Internal
+	'parentEntityType', 'parentEntityId', 'fieldName', 'targetType', 'store', 'dispatcher',
+	'placeholderId', 'createPlaceholderFieldHandle',
+])
+
+/**
+ * Configuration for creating a handle proxy.
+ */
+export interface HandleProxyConfig<T extends object> {
+	/** Set of property names that should pass through to the handle */
+	knownProperties: Set<string | symbol>
+	/** Function to get the fields proxy from the handle */
+	getFields: (target: T) => object
+}
+
+/**
+ * Creates a proxy around a handle that supports direct field access.
+ *
+ * - `handle.fieldName` is equivalent to `handle.$fields.fieldName`
+ * - `handle.$propertyName` accesses handle properties with $ prefix stripped
+ * - Known properties pass through directly to the handle
+ *
+ * @param handle - The handle instance to wrap
+ * @param config - Configuration for the proxy
+ * @returns Proxied handle with direct field access support
+ */
+export function createHandleProxy<T extends object>(
+	handle: T,
+	config: HandleProxyConfig<T>,
+): T {
+	return new Proxy(handle, {
+		get(target, prop, _receiver) {
+			// Symbols and non-string props - pass through
+			if (typeof prop !== 'string') {
+				return Reflect.get(target, prop, target)
+			}
+
+			// $ prefixed - strip $ and access handle property
+			if (prop.startsWith('$')) {
+				const realProp = prop.slice(1)
+				// Use target as receiver so getters use target as `this`, not the Proxy
+				const value = Reflect.get(target, realProp, target)
+				// Bind methods to preserve `this`
+				if (typeof value === 'function') {
+					return value.bind(target)
+				}
+				return value
+			}
+
+			// Known handle properties - pass through for backwards compatibility
+			if (config.knownProperties.has(prop)) {
+				const value = Reflect.get(target, prop, target)
+				if (typeof value === 'function') {
+					return value.bind(target)
+				}
+				return value
+			}
+
+			// Otherwise, treat as field access
+			const fields = config.getFields(target)
+			return (fields as Record<string, unknown>)[prop]
+		},
+
+		has(target, prop) {
+			if (typeof prop === 'string' && !config.knownProperties.has(prop) && !prop.startsWith('$')) {
+				// Check if it's a field
+				const fields = config.getFields(target)
+				return prop in fields
+			}
+			return Reflect.has(target, prop)
+		},
+	})
+}
+
+/**
+ * Creates a simple proxy that only handles $ prefix aliasing.
+ * Used for handles that don't need field access proxying (FieldHandle, HasManyListHandle, PlaceholderHandle).
+ *
+ * - `handle.$propertyName` accesses `handle.propertyName`
+ * - All other accesses pass through to the handle
+ *
+ * @param handle - The handle instance to wrap
+ * @returns Proxied handle with $ alias support
+ */
+export function createAliasProxy<T extends object>(handle: T): T {
+	return new Proxy(handle, {
+		get(target, prop, _receiver) {
+			// Symbols and non-string props - pass through
+			if (typeof prop !== 'string') {
+				return Reflect.get(target, prop, target)
+			}
+
+			// $ prefixed - strip $ and access handle property
+			if (prop.startsWith('$')) {
+				const realProp = prop.slice(1)
+				const value = Reflect.get(target, realProp, target)
+				// Bind methods to preserve `this`
+				if (typeof value === 'function') {
+					return value.bind(target)
+				}
+				return value
+			}
+
+			// Pass through to handle
+			const value = Reflect.get(target, prop, target)
+			if (typeof value === 'function') {
+				return value.bind(target)
+			}
+			return value
+		},
+	})
+}