@wovin/core 0.2.2 → 0.3.2

package/src/viewmodel/examples/all-adapters.ts

@@ -0,0 +1,206 @@
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * Schema Adapter Examples
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * This file demonstrates how to use each schema adapter with the
+ * generic ViewModel factory. Uncomment the adapter you want to use.
+ *
+ * Each section is self-contained and shows:
+ * 1. Schema definition
+ * 2. Adapter creation
+ * 3. ViewModel factory usage
+ * 4. Basic VM usage
+ *
+ * Note: Not all schema libraries are installed as dependencies.
+ *   ✓ TypeBox — peer dependency of @wovin/core (available)
+ *   ✓ Zod — dependency of @wovin/core (available)
+ *   ✗ ArkType — NOT installed (example shown for pattern reference)
+ *   ✗ Typia — NOT installed (example shown for pattern reference)
+ */
+
+import { createViewModelFactory, ObjectBuilder, type ISchemaAdapter, type VMAttributeDef } from '../index.ts'
+import type { Thread } from '../../thread/basic.ts'
+import type { ApplogValue, EntityID } from '../../applog/datom-types.ts'
+
+// ═══════════════════════════════════════════════════════════════
+// Shared helpers for examples
+// ═══════════════════════════════════════════════════════════════
+
+/** Dummy thread for examples */
+function createMockThread(): Thread {
+	return { name: 'mock', applogs: [], filters: [], subscribe: () => () => {} } as unknown as Thread
+}
+
+interface Note extends Record<string, ApplogValue> {
+	title: string
+	body: string
+	tags?: string
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 1. TypeBox Adapter Example
+// ═══════════════════════════════════════════════════════════════
+
+// import { Type } from '@sinclair/typebox'
+// import { Static } from '@sinclair/typebox'
+// import { createTypeBoxAdapter } from '../adapters/typebox.ts'
+
+export function typeBoxExample() {
+	/*
+
+	const NoteSchema = Type.Object({
+		title: Type.String(),
+		body: Type.String(),
+		tags: Type.Optional(Type.String()),
+	})
+	type Note = Static<typeof NoteSchema>
+
+	const NoteVM = createViewModelFactory<Note>({
+		adapter: createTypeBoxAdapter(NoteSchema, 'note', {
+			atOverrides: {
+				title: 'note/title',
+				body: 'note/body',
+				tags: 'note/tags',
+			},
+		}),
+		vmName: 'Note',
+	})
+
+	const thread = createMockThread()
+	const note = NoteVM.get('abc123' as EntityID, thread)
+	console.log(note.title) // reactive read
+	note.title = 'Hello'   // writes to thread via applog
+
+	*/
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 2. Zod Adapter Example
+// ═══════════════════════════════════════════════════════════════
+
+// import { z } from 'zod'
+// import { createZodAdapter } from '../adapters/zod.ts'
+
+export function zodExample() {
+	/*
+
+	const NoteSchema = z.object({
+		title: z.string(),
+		body: z.string(),
+		tags: z.string().optional(),
+	})
+	type Note = z.infer<typeof NoteSchema>
+
+	const NoteVM = createViewModelFactory<Note>({
+		adapter: createZodAdapter(NoteSchema, 'note', {
+			atOverrides: {
+				title: 'note/title',
+				body: 'note/body',
+				tags: 'note/tags',
+			},
+		}),
+		vmName: 'Note',
+	})
+
+	const thread = createMockThread()
+	const note = NoteVM.get('abc123' as EntityID, thread)
+	console.log(note.title)
+	note.title = 'Hello'
+
+	*/
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 3. ArkType Adapter Pattern
+// ═══════════════════════════════════════════════════════════════
+// ArkType is NOT a dependency. This shows the pattern if you install it.
+
+// import { createArkTypeAdapter } from '../adapters/arktype.ts'
+
+export function arkTypePattern() {
+	/*
+
+	// First, define attributes manually (ArkType doesn't expose runtime props)
+	const attrs: VMAttributeDef[] = [
+		{ name: 'title', atPath: 'note/title', optional: false },
+		{ name: 'body', atPath: 'note/body', optional: false },
+		{ name: 'tags', atPath: 'note/tags', optional: true },
+	]
+
+	// Then create the adapter with a validator
+	// import { type } from 'arktype'
+	// const NoteSchema = type({ title: 'string', body: 'string', 'tags?': 'string' })
+
+	const NoteVM = createViewModelFactory<Note>({
+		adapter: createArkTypeAdapter(
+			// NoteSchema, // your arktype validator
+			{} as any, // placeholder
+			'note',
+			{ attributes: attrs },
+		),
+		vmName: 'Note',
+	})
+
+	*/
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 4. Typia Adapter Pattern
+// ═══════════════════════════════════════════════════════════════
+// Typia is NOT a dependency. This shows the pattern if you install it.
+
+// import { createTypiaAdapter } from '../adapters/typia.ts'
+
+export function typiaPattern() {
+	/*
+
+	// Define attributes manually (Typia strips types at compile time)
+	const attrs: VMAttributeDef[] = [
+		{ name: 'title', atPath: 'note/title', optional: false },
+		{ name: 'body', atPath: 'note/body', optional: false },
+		{ name: 'tags', atPath: 'note/tags', optional: true },
+	]
+
+	// Then create the adapter with a typia validator
+	// import typia from 'typia'
+	// interface Note { title: string; body: string; tags?: string }
+	// const validate = typia.createValidate<Note>()
+
+	const NoteVM = createViewModelFactory<Note>({
+		adapter: createTypiaAdapter(
+			// validate, // your typia validator
+			{} as any, // placeholder
+			'note',
+			{ attributes: attrs },
+		),
+		vmName: 'Note',
+	})
+
+	*/
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 5. Minimal adapter (no schema library)
+// ═══════════════════════════════════════════════════════════════
+
+export function minimalNoSchemaExample() {
+	// You don't need a schema library at all — use createAdapterFromAttributes
+
+	const adapter: ISchemaAdapter<Note> = {
+		getAttributeDefs: (): VMAttributeDef[] => [
+			{ name: 'title', atPath: 'note/title', optional: false },
+			{ name: 'body', atPath: 'note/body', optional: false },
+			{ name: 'tags', atPath: 'note/tags', optional: true },
+		],
+		getDefaults: () => ({ title: '', body: '' }),
+		getEntityPrefix: () => 'note',
+	}
+
+	const NoteVM = createViewModelFactory<Note>({
+		adapter,
+		vmName: 'Note',
+	})
+
+	console.log('Minimal NoteVM created:', NoteVM.vmName)
+}

package/src/viewmodel/factory.ts

@@ -0,0 +1,330 @@
+import type { ApplogForInsertOptionalAgent, ApplogValue, EntityID } from '../applog/datom-types.ts'
+import { EntityID_LENGTH } from '../applog/datom-types.ts'
+import { dateNowIso, mintNewEntity } from '../applog/applog-utils.ts'
+import { ensureTsPvAndFinalizeApplog } from '../applog/applog-helpers.ts'
+import { lastWriteWins, liveEntityAt } from '../query/basic.ts'
+import { SubscribableImpl } from '../query/subscribable.ts'
+import type { Thread } from '../thread/basic.ts'
+import { isInitEvent } from '../thread/basic.ts'
+import { rollingFilter } from '../thread/filters.ts'
+import { ObjectBuilder } from './builder.ts'
+import {
+	type ISignalAdapter,
+	type IVMInstance,
+	type ViewModelFactoryOptions,
+	type VMInstanceMap,
+	getInstancesForThread,
+} from './types.ts'
+
+// ═══════════════════════════════════════════════════════════════
+// Default (non-reactive) Signal Adapter
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Default signal adapter — reads Subscribable values directly (snapshot).
+ * Subscribe-once to keep .value current. No framework reactivity.
+ */
+export const DefaultSignalAdapter: ISignalAdapter = {
+	createGetter<T>(subscribable: { value: T; subscribe(cb: () => void): () => void }): () => T {
+		// Subscribe once to activate upstream (lazy activation)
+		subscribable.subscribe(() => {})
+		return () => subscribable.value
+	},
+	createWritable<T>(initial: T): [() => T, (v: T) => void] {
+		let current = initial
+		return [() => current, (v: T) => { current = v }]
+	},
+}
+
+// ═══════════════════════════════════════════════════════════════
+// makeCurrentThread - convenience wrapper
+// ═══════════════════════════════════════════════════════════════
+
+function makeCurrent(thread: Thread, fn?: ViewModelFactoryOptions<any>['makeCurrentThread']): Thread {
+	if (fn) return fn(thread)
+	return lastWriteWins(thread, { tolerateAlreadyFiltered: true })
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Default persist function
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Default applog persistence: finalize applogs and push into thread.
+ * Works with WriteableThread (which has insertRaw).
+ */
+function defaultPersistApplogs(thread: Thread, applogs: ApplogForInsertOptionalAgent[]): void {
+	const finalized = applogs.map(log => ensureTsPvAndFinalizeApplog(log as any, thread))
+	const writable = thread as any
+	if (typeof writable.insertRaw === 'function') {
+		writable.insertRaw(finalized)
+	} else if (typeof writable.insert === 'function') {
+		writable.insert(applogs)
+	} else {
+		// Read-only thread — just finalize but don't persist
+		// This is fine for optimistic UI or read-only scenarios
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// createViewModelFactory - THE MAIN FACTORY
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Create a ViewModel factory for a given schema.
+ *
+ * Returns a base class that can be extended or used directly.
+ * The class provides:
+ * - Static `get(en, thread)` for singleton access
+ * - Static `buildNew(init, en)` for creating entities
+ * - Instance `buildUpdate(init)` for updating entities
+ * - Lazy reactive property accessors per attribute
+ * - `setDeleted()` for soft deletion
+ *
+ * Framework-specific reactivity (Solid, Vue, etc.) can be added by
+ * providing a custom `ISignalAdapter` in the options.
+ *
+ * @param options - Factory configuration
+ * @returns A VM class constructor with static methods
+ */
+export function createViewModelFactory<T extends Record<string, ApplogValue>>(
+	options: ViewModelFactoryOptions<T>,
+) {
+	const {
+		adapter,
+		entityPrefix = adapter.getEntityPrefix(),
+		entityIdLength = EntityID_LENGTH,
+		generateEntityId,
+		vmName = entityPrefix,
+		signalAdapter = DefaultSignalAdapter,
+	} = options
+
+	const attrDefs = adapter.getAttributeDefs()
+	const defaults = adapter.getDefaults()
+
+	// Entity ID generation
+	const genId = generateEntityId ?? ((data: Partial<T> & { ts?: string }) =>
+		mintNewEntity({ ...data, ts: data.ts ?? dateNowIso() }, entityIdLength) as EntityID)
+
+	// Persist function (can be overridden by extending class)
+	const persistFn = (thread: Thread, applogs: ApplogForInsertOptionalAgent[]) => {
+		defaultPersistApplogs(thread, applogs)
+	}
+
+	// ═══════════════════════════════════════════════════════════════
+	// The ViewModel Class
+	// ═══════════════════════════════════════════════════════════════
+	class ViewModel {
+		/** Per-instance signal storage */
+		_signals = new Map<string, () => ApplogValue>()
+		_signalAdapter: ISignalAdapter = signalAdapter
+
+		/** Reactive map for applog tracking: vl === this.en */
+		_targetMap: SubscribableImpl<Map<EntityID, Set<string>>>
+
+		/** Applogs in the current thread where vl === this.en */
+		_targetApplogs: Thread
+
+		constructor(
+			public en: EntityID,
+			public thread: Thread,
+			skipInit?: boolean,
+		) {
+			if (skipInit) return
+
+			const currentThread = makeCurrent(thread, options.makeCurrentThread)
+
+			// Define lazy getters/setters for each attribute
+			for (const attr of attrDefs) {
+				if (attr.name === 'en') continue
+
+				const attrName = attr.name
+				const atPath = attr.atPath
+				const defaultValue = attr.defaultValue ?? defaults?.[attrName as keyof T]
+
+				Object.defineProperty(this, attrName, {
+					get(this: ViewModel) {
+						let signal = this._signals.get(attrName)
+						if (!signal) {
+							const subscribable = liveEntityAt(currentThread, this.en, atPath)
+							signal = this._signalAdapter.createGetter(subscribable)
+							this._signals.set(attrName, signal)
+						}
+						const value = signal()
+						return value ?? (defaultValue as ApplogValue | undefined) ?? value
+					},
+					set(this: ViewModel, v: ApplogValue) {
+						const applog: ApplogForInsertOptionalAgent = { en: this.en, at: atPath, vl: v }
+						persistFn(this.thread, [applog])
+					},
+					enumerable: true,
+					configurable: true,
+				})
+			}
+
+			// ── Applog tracking: applogs where vl === this.en ────────────
+			const targets = new Map<EntityID, Set<string>>()
+
+			this._targetApplogs = rollingFilter(currentThread, { vl: this.en })
+			this._targetMap = new SubscribableImpl(
+				targets,
+				() => this._targetApplogs.subscribe((event) => {
+					if (isInitEvent(event)) {
+						targets.clear()
+						for (const log of event.init) {
+							let ats = targets.get(log.en)
+							if (!ats) {
+								ats = new Set()
+								targets.set(log.en, ats)
+							}
+							ats.add(log.at)
+						}
+					} else {
+						for (const log of event.added) {
+							let ats = targets.get(log.en)
+							if (!ats) {
+								ats = new Set()
+								targets.set(log.en, ats)
+							}
+							ats.add(log.at)
+						}
+						if (event.removed) {
+							for (const log of event.removed) {
+								const ats = targets.get(log.en)
+								if (ats) {
+									ats.delete(log.at)
+									if (ats.size === 0) targets.delete(log.en)
+								}
+							}
+						}
+					}
+					this._targetMap._set(targets)
+				}, 'derived'),
+			)
+		}
+
+		/** Thread scoped to this entity */
+		get entityThread(): Thread {
+			return rollingFilter(this.thread, { en: this.en })
+		}
+
+		/** Applogs in the current thread where vl === this.en */
+		get targetApplogs(): Thread {
+			return this._targetApplogs
+		}
+
+		/** Set of entities that have an applog with this.en as the vl */
+		get targettedBy(): Set<EntityID> {
+			return new Set(this._targetMap.value.keys())
+		}
+
+		/** Set of at strings from applogs where vl === this.en */
+		get targettedVia(): Set<string> {
+			const via = new Set<string>()
+			for (const ats of this._targetMap.value.values()) {
+				for (const at of ats) via.add(at)
+			}
+			return via
+		}
+
+		/** Whether this entity is soft-deleted */
+		get isDeleted(): boolean {
+			let signal = this._signals.get('__isDeleted')
+			if (!signal) {
+				const currentThread = makeCurrent(this.thread, options.makeCurrentThread)
+				const subscribable = liveEntityAt(currentThread, this.en, 'isDeleted')
+				signal = this._signalAdapter.createGetter(subscribable)
+				this._signals.set('__isDeleted', signal)
+			}
+			return !!signal()
+		}
+
+		/** Soft-delete this entity */
+		setDeleted(thread = this.thread): void {
+			const applog: ApplogForInsertOptionalAgent = { en: this.en, at: 'isDeleted', vl: true }
+			persistFn(thread, [applog])
+		}
+
+		/** Get a builder for updating this entity */
+		buildUpdate(init: Partial<T> = {}): ObjectBuilder<T> {
+			return new ObjectBuilder<T>(init, this.en, entityPrefix)
+		}
+
+		/** Description for debugging */
+		get description(): string {
+			return `${vmName}VM(en=${this.en})`
+		}
+
+		/** Get the full entity state as a plain object */
+		toJSON(): Partial<T> {
+			const result: Record<string, ApplogValue> = {}
+			for (const attr of attrDefs) {
+				const value = (this as any)[attr.name]
+				if (value !== undefined && value !== null) {
+					result[attr.name] = value
+				}
+			}
+			return result as Partial<T>
+		}
+	}
+
+	// ── Static Methods ────────────────────────────────────────────
+
+	/**
+	 * Get or create a VM instance for the given entity and thread.
+	 * Implements the singleton pattern — returns cached instance if one exists.
+	 */
+	function getVMClass(en: EntityID, thread: Thread): InstanceType<typeof ViewModel> {
+		if (!en || typeof en !== 'string') throw new Error(`[${vmName}VM.get] invalid en: ${en}`)
+		if (!thread) throw new Error(`[${vmName}VM.get] no thread provided`)
+
+		const threadMap = getInstancesForThread(thread)
+		let entityMap = threadMap.get(vmName) as VMInstanceMap<InstanceType<typeof ViewModel>> | undefined
+		if (!entityMap) {
+			entityMap = new Map()
+			threadMap.set(vmName, entityMap)
+		}
+
+		const existing = entityMap.get(en)
+		if (existing) return existing
+
+		const vm = new ViewModel(en, thread, false) as InstanceType<typeof ViewModel>
+		entityMap.set(en, vm)
+		return vm
+	}
+
+	/**
+	 * Create a builder for constructing a new entity.
+	 */
+	function buildNewEntity(init: Partial<T> = {}, en?: EntityID): ObjectBuilder<T> {
+		const entityId = en ?? genId(init as any)
+		return ObjectBuilder.create<T>(init, entityId, entityPrefix)
+	}
+
+	// Attach static methods to the class
+	const VMClass: any = ViewModel
+	VMClass.get = getVMClass
+	VMClass.buildNew = buildNewEntity
+	VMClass.vmName = vmName
+	VMClass.entityPrefix = entityPrefix
+
+	return VMClass as unknown as {
+		new(
+			en: EntityID,
+			thread: Thread,
+			skipInit?: boolean,
+		): IVMInstance<T> & T
+
+		/** Get or create a VM instance for the given entity ID */
+		get(en: EntityID, thread: Thread): IVMInstance<T> & T
+
+		/** Create a builder for a new entity */
+		buildNew(init?: Partial<T>, en?: EntityID): ObjectBuilder<T>
+
+		/** The VM name (for debugging) */
+		readonly vmName: string
+
+		/** The entity prefix used for at-paths */
+		readonly entityPrefix: string
+	}
+}

package/src/viewmodel/index.ts

@@ -0,0 +1,22 @@
+// Core ViewModel Abstraction
+// Framework-agnostic ViewModel factory system for wovin threads
+
+export { ObjectBuilder } from './builder.ts'
+export { createViewModelFactory, DefaultSignalAdapter } from './factory.ts'
+export { createAdapterFromAttributes, buildAtPath } from './schema-adapter.ts'
+export type {
+	ISchemaAdapter,
+	ISignalAdapter,
+	IVMInstance,
+	IVMClass,
+	VMAttributeDef,
+	ViewModelFactoryOptions,
+	VMInstanceMap,
+} from './types.ts'
+export { GlobalVMInstances, getInstancesForThread } from './types.ts'
+
+// Schema Adapters
+export { createTypeBoxAdapter } from './adapters/typebox.ts'
+export { createZodAdapter } from './adapters/zod.ts'
+export { createArkTypeAdapter } from './adapters/arktype.ts'
+export { createTypiaAdapter } from './adapters/typia.ts'

package/src/viewmodel/schema-adapter.ts

@@ -0,0 +1,27 @@
+import type { ApplogValue } from '../applog/datom-types.ts'
+import type { ISchemaAdapter, VMAttributeDef } from './types.ts'
+
+/**
+ * Helper to create a simple schema adapter from a plain attribute list.
+ * Useful for quick VM definitions or when you don't have a formal schema library.
+ */
+export function createAdapterFromAttributes<T extends Record<string, ApplogValue>>(
+	config: {
+		attributes: VMAttributeDef[]
+		entityPrefix: string
+		defaults?: Partial<T>
+	},
+): ISchemaAdapter<T> {
+	return {
+		getAttributeDefs: () => config.attributes,
+		getDefaults: () => (config.defaults ?? {}) as Partial<T>,
+		getEntityPrefix: () => config.entityPrefix,
+	}
+}
+
+/**
+ * Helper to build at-paths from attribute names and an entity prefix.
+ */
+export function buildAtPath(entityPrefix: string, attrName: string): string {
+	return `${entityPrefix}/${attrName}`
+}