@contember/bindx 0.1.14 → 0.1.16

package/src/handles/EntityHandle.ts

@@ -11,7 +11,7 @@ import {
 	clearEntityErrors,
 	clearAllErrors as clearAllErrorsAction,
 } from '../core/actions.js'
-import { type FieldRef, type HasOneAccessor, type HasManyRef, type SelectedEntityFields, type Unsubscribe, type EntityAccessor } from './types.js'
+import { type FieldAccessor, type HasOneAccessor, type HasManyAccessor, type EntityFieldsAccessor, type Unsubscribe, type EntityAccessor } from './types.js'
 import { deepEqual } from '../utils/deepEqual.js'
 import { createClientError, type ErrorInput, type FieldError } from '../errors/types.js'
 import type {
@@ -38,12 +38,12 @@ interface RelationHandleRaw {
 
 interface CachedFieldHandle {
 	readonly raw: FieldHandle<unknown>
-	readonly proxy: FieldRef<unknown>
+	readonly proxy: FieldAccessor<unknown>
 }
 
 interface CachedRelationHandle {
 	readonly raw: RelationHandleRaw
-	readonly proxy: HasOneAccessor<object> | HasManyRef<object>
+	readonly proxy: HasOneAccessor<object> | HasManyAccessor<object>
 }
 
 /**
@@ -241,12 +241,12 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	 * Gets a field handle for a specific field.
 	 * Returns cached handle to ensure stable identity.
 	 */
-	field<K extends keyof T>(fieldName: K): FieldRef<T[K]> {
+	field<K extends keyof T>(fieldName: K): FieldAccessor<T[K]> {
 		const cacheKey = String(fieldName)
 		const cached = this.fieldHandleCache.get(cacheKey)
 
 		if (cached) {
-			return cached.proxy as FieldRef<T[K]>
+			return cached.proxy as FieldAccessor<T[K]>
 		}
 
 		const enumName = this.schema.getEnumName(this.entityType, cacheKey)
@@ -307,13 +307,13 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	 * @param alias - Optional alias for the relation. When the same field is used multiple times
 	 *                with different parameters (filter, orderBy, limit), each needs a unique alias.
 	 */
-	hasMany<TItem extends object>(fieldName: string, alias?: string, nestedSelection?: SelectionMeta): HasManyRef<TItem> {
+	hasMany<TItem extends object>(fieldName: string, alias?: string, nestedSelection?: SelectionMeta): HasManyAccessor<TItem> {
 		const effectiveAlias = alias ?? fieldName
 		const cacheKey = `hasMany:${effectiveAlias}`
 		const cached = this.relationHandleCache.get(cacheKey)
 
 		if (cached) {
-			return cached.proxy as HasManyRef<TItem>
+			return cached.proxy as HasManyAccessor<TItem>
 		}
 
 		const targetType = this.schema.getRelationTarget(this.entityType, fieldName)
@@ -380,12 +380,12 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	 * Gets a raw (unproxied) has-many relation handle from cache.
 	 * Creates the handle if not cached yet.
 	 */
-	private getHasManyHandleRaw(fieldName: string): HasManyRef<object> {
+	private getHasManyHandleRaw(fieldName: string): HasManyAccessor<object> {
 		const cacheKey = `hasMany:${fieldName}`
 		const cached = this.relationHandleCache.get(cacheKey)
 
 		if (cached) {
-			return cached.proxy as HasManyRef<object>
+			return cached.proxy as HasManyAccessor<object>
 		}
 
 		const targetType = this.schema.getRelationTarget(this.entityType, fieldName)
@@ -460,8 +460,8 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	 *
 	 * Implements EntityRef.fields - returns selection-aware field accessors.
 	 */
-	get fields(): SelectedEntityFields<T, TSelected> {
-		return new Proxy({} as SelectedEntityFields<T, TSelected>, {
+	get fields(): EntityFieldsAccessor<T, TSelected> {
+		return new Proxy({} as EntityFieldsAccessor<T, TSelected>, {
 			get: (_, fieldName: string) => {
 				// Selection validation
 				if (this.selection && !this.selection.fields.has(fieldName)) {

package/src/handles/FieldHandle.ts

@@ -2,7 +2,7 @@ import { EntityRelatedHandle } from './BaseHandle.js'
 import type { ActionDispatcher } from '../core/ActionDispatcher.js'
 import type { SnapshotStore } from '../store/SnapshotStore.js'
 import { addFieldError, clearFieldErrors, setField } from '../core/actions.js'
-import { FIELD_REF_META, type FieldRef, type FieldRefMeta, type InputProps, type Unsubscribe } from './types.js'
+import { FIELD_REF_META, type FieldAccessor, type FieldRefMeta, type InputProps, type Unsubscribe } from './types.js'
 import { deepEqual } from '../utils/deepEqual.js'
 import { createClientError, type ErrorInput, type FieldError } from '../errors/types.js'
 import type {
@@ -49,8 +49,8 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 		dispatcher: ActionDispatcher,
 		enumName?: string,
 		columnType?: string,
-	): FieldRef<T> {
-		return createAliasProxy<FieldHandle<T>, FieldRef<T>>(new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType))
+	): FieldAccessor<T> {
+		return createAliasProxy<FieldHandle<T>, FieldAccessor<T>>(new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType))
 	}
 
 	static createRaw<T = unknown>(
@@ -65,8 +65,8 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 		return new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType)
 	}
 
-	static wrapProxy<T>(handle: FieldHandle<T>): FieldRef<T> {
-		return createAliasProxy<FieldHandle<T>, FieldRef<T>>(handle)
+	static wrapProxy<T>(handle: FieldHandle<T>): FieldAccessor<T> {
+		return createAliasProxy<FieldHandle<T>, FieldAccessor<T>>(handle)
 	}
 
 	/**
@@ -220,7 +220,7 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 	 */
 	nested<K extends keyof NonNullable<T>>(
 		key: K,
-	): FieldRef<NonNullable<T>[K]> {
+	): FieldAccessor<NonNullable<T>[K]> {
 		return FieldHandle.create<NonNullable<T>[K]>(
 			this.entityType,
 			this.entityId,

package/src/handles/HasManyListHandle.ts

@@ -8,7 +8,7 @@ import {
 	addRelationError,
 	clearRelationErrors,
 } from '../core/actions.js'
-import { FIELD_REF_META, type HasManyRef, type FieldRefMeta, type EntityAccessor, type Unsubscribe } from './types.js'
+import { FIELD_REF_META, type HasManyAccessor, type FieldRefMeta, type EntityAccessor, type Unsubscribe } from './types.js'
 import { createClientError, type ErrorInput, type FieldError } from '../errors/types.js'
 import type {
 	EventListener,
@@ -85,8 +85,8 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 		brands?: Set<symbol>,
 		alias?: string,
 		selection?: SelectionMeta,
-	): HasManyRef<TEntity, TSelected> {
-		return createAliasProxy<HasManyListHandle<TEntity, TSelected>, HasManyRef<TEntity, TSelected>>(new HasManyListHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, itemType, store, dispatcher, schema, brands, alias, selection))
+	): HasManyAccessor<TEntity, TSelected> {
+		return createAliasProxy<HasManyListHandle<TEntity, TSelected>, HasManyAccessor<TEntity, TSelected>>(new HasManyListHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, itemType, store, dispatcher, schema, brands, alias, selection))
 	}
 
 	/**

package/src/handles/HasOneHandle.ts

@@ -13,7 +13,7 @@ import {
 import {
 	FIELD_REF_META,
 	type FieldRefMeta,
-	type SelectedEntityFields,
+	type EntityFieldsAccessor,
 	type Unsubscribe,
 	type EntityAccessor,
 	type HasOneAccessor,
@@ -198,7 +198,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Implements HasOneRef interface.
 	 * Delegates to the entity (either real EntityHandle or PlaceholderHandle).
 	 */
-	get fields(): SelectedEntityFields<TEntity, TSelected> {
+	get fields(): EntityFieldsAccessor<TEntity, TSelected> {
 		return this.entity.$fields
 	}
 
@@ -236,6 +236,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 				this.targetType,
 				this.store,
 				this.dispatcher,
+				this.schema,
 				this.__brands,
 			)
 			this.placeholderCacheProxy = PlaceholderHandle.wrapProxy(this.placeholderCacheRaw)

package/src/handles/PlaceholderHandle.ts

@@ -3,7 +3,7 @@ import type { SnapshotStore } from '../store/SnapshotStore.js'
 import { generatePlaceholderId } from '../store/SnapshotStore.js'
 import {
 	FIELD_REF_META,
-	type SelectedEntityFields,
+	type EntityFieldsAccessor,
 	type FieldRefMeta,
 	type Unsubscribe,
 	type EntityAccessor,
@@ -19,6 +19,7 @@ import type {
 	EntityPersistingEvent,
 } from '../events/types.js'
 import { createAliasProxy } from './proxyFactory.js'
+import type { SchemaRegistry } from '../schema/SchemaRegistry.js'
 
 /**
  * PlaceholderHandle provides access to a placeholder entity (for creating new entities).
@@ -42,6 +43,7 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 		private readonly targetType: string,
 		private readonly store: SnapshotStore,
 		private readonly dispatcher: ActionDispatcher,
+		private readonly schema: SchemaRegistry | null,
 		brands?: Set<symbol>,
 	) {
 		this.__brands = brands
@@ -55,9 +57,10 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 		targetType: string,
 		store: SnapshotStore,
 		dispatcher: ActionDispatcher,
+		schema?: SchemaRegistry | null,
 		brands?: Set<symbol>,
 	): EntityAccessor<TEntity, TSelected> {
-		return PlaceholderHandle.wrapProxy(new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, brands))
+		return PlaceholderHandle.wrapProxy(new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema ?? null, brands))
 	}
 
 	static createRaw<TEntity extends object = object, TSelected = TEntity>(
@@ -67,9 +70,10 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 		targetType: string,
 		store: SnapshotStore,
 		dispatcher: ActionDispatcher,
+		schema?: SchemaRegistry | null,
 		brands?: Set<symbol>,
 	): PlaceholderHandle<TEntity, TSelected> {
-		return new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, brands)
+		return new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema ?? null, brands)
 	}
 
 	static wrapProxy<TEntity extends object, TSelected>(handle: PlaceholderHandle<TEntity, TSelected>): EntityAccessor<TEntity, TSelected> {
@@ -134,8 +138,8 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 	/**
 	 * Gets field accessors that read/write placeholder data.
 	 */
-	get fields(): SelectedEntityFields<TEntity, TSelected> {
-		return new Proxy({} as SelectedEntityFields<TEntity, TSelected>, {
+	get fields(): EntityFieldsAccessor<TEntity, TSelected> {
+		return new Proxy({} as EntityFieldsAccessor<TEntity, TSelected>, {
 			get: (_, fieldName: string) => {
 				return this.createPlaceholderFieldHandle(fieldName)
 			},
@@ -144,8 +148,24 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 
 	/**
 	 * Creates a field handle for placeholder data.
+	 * For has-many relations, returns an empty has-many-like handle with items/map/length.
 	 */
 	private createPlaceholderFieldHandle(fieldName: string): unknown {
+		// For has-many relations, return an empty has-many-like handle
+		if (this.schema?.isHasMany(this.targetType, fieldName)) {
+			const emptyItems: EntityAccessor<object>[] = []
+			const emptyHasMany: Record<string, unknown> = {
+				get items() { return emptyItems },
+				get length() { return 0 },
+				map: () => [],
+				add: () => { throw new Error(`Cannot add items to disconnected has-many relation "${fieldName}" on placeholder entity`) },
+				remove: () => {},
+				$state: 'disconnected',
+				[Symbol.iterator]: () => emptyItems[Symbol.iterator](),
+			}
+			return emptyHasMany
+		}
+
 		const self = this
 
 		return {

package/src/handles/index.ts

@@ -8,27 +8,25 @@ export {
 	FIELD_REF_META,
 	type HasOneRelationState,
 	type EntityFields,
-	type SelectedEntityFields,
-	type SelectedEntityFieldsBase,
+	type EntityFieldsAccessor,
+	type EntityFieldsRef,
 	type ScalarKeys,
 	type HasManyKeys,
 	type HasOneKeys,
 	type FieldRefMeta,
 	type InputProps,
-	// Full types (for explicit selection - have .value, .length, etc.)
+	// Ref types (pointer, no data access)
 	type FieldRef,
 	type HasManyRef,
 	type HasOneRef,
-	type HasOneAccessor,
+	type HasOneRefInterface,
 	type EntityRef,
+	type EntityRefInterface,
+	// Accessor types (live data access, extends Ref)
+	type FieldAccessor,
+	type HasManyAccessor,
+	type HasOneAccessor,
 	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,