@stonecrop/stonecrop 0.4.37 → 0.6.0

package/src/index.ts

@@ -1,11 +1,57 @@
 export type * from '@stonecrop/aform/types'
 export type * from '@stonecrop/atable/types'
 
-import { type StonecropReturn, useStonecrop } from './composable'
+import { useStonecrop } from './composable'
+import { useOperationLog, useUndoRedoShortcuts, withBatch } from './composables/operation-log'
 import DoctypeMeta from './doctype'
+import {
+	getGlobalTriggerEngine,
+	markOperationIrreversible,
+	registerGlobalAction,
+	registerTransitionAction,
+	setFieldRollback,
+	triggerTransition,
+} from './field-triggers'
+import plugin from './plugins'
 import Registry from './registry'
-import Stonecrop from './plugins'
-import { Stonecrop as StonecropClass } from './stonecrop'
+import { Stonecrop } from './stonecrop'
+import { HST, createHST, type HSTNode } from './stores/hst'
+import { useOperationLogStore } from './stores/operation-log'
 export type * from './types'
+export type { BaseStonecropReturn, HSTChangeData, HSTStonecropReturn, OperationLogAPI } from './composable'
+export type { FieldTriggerEngine } from './field-triggers'
+export type {
+	FieldChangeContext,
+	TransitionChangeContext,
+	FieldTriggerExecutionResult,
+	ActionExecutionResult,
+	TransitionExecutionResult,
+	FieldActionFunction,
+	TransitionActionFunction,
+} from './types/field-triggers'
 
-export { DoctypeMeta, Registry, Stonecrop, StonecropClass, StonecropReturn, useStonecrop }
+export {
+	DoctypeMeta,
+	Registry,
+	Stonecrop,
+	useStonecrop,
+	// HST exports for advanced usage
+	HST,
+	createHST,
+	HSTNode,
+	// Field trigger system exports
+	getGlobalTriggerEngine,
+	registerGlobalAction,
+	registerTransitionAction,
+	setFieldRollback,
+	triggerTransition,
+	markOperationIrreversible,
+	// Operation log exports
+	useOperationLog,
+	useOperationLogStore,
+	useUndoRedoShortcuts,
+	withBatch,
+}
+
+// Default export is the Vue plugin
+export default plugin

package/src/plugins/index.ts

@@ -1,8 +1,29 @@
-import { App, type Plugin } from 'vue'
+import { App, type Plugin, nextTick } from 'vue'
+import type { Pinia } from 'pinia'
 
 import Registry from '../registry'
-import { pinia } from '../stores'
+import { Stonecrop } from '../stonecrop'
 import type { InstallOptions } from '../types'
+import { useOperationLogStore } from '../stores/operation-log'
+
+/**
+ * Setup auto-initialization for user-defined initialization logic
+ * This function handles the post-mount initialization automatically
+ */
+async function setupAutoInitialization(
+	registry: Registry,
+	stonecrop: Stonecrop,
+	onRouterInitialized: (registry: Registry, stonecrop: Stonecrop) => void | Promise<void>
+) {
+	// Wait for the next tick to ensure the app is mounted
+	await nextTick()
+
+	try {
+		await onRouterInitialized(registry, stonecrop)
+	} catch {
+		// Silent error handling - application should handle initialization errors
+	}
+}
 
 /**
  * Stonecrop Vue plugin
@@ -10,47 +31,74 @@ import type { InstallOptions } from '../types'
  * @param options - The plugin options
  * @example
  * ```ts
- *
  * import { createApp } from 'vue'
- * import Stonecrop from 'stonecrop'
- *
- * import App from './App.vue'
+ * import Stonecrop from '@stonecrop/stonecrop'
+ * import router from './router'
  *
  * const app = createApp(App)
  * app.use(Stonecrop, {
- *  router,
- *  components: {
- *   // register custom components
- *  },
- *  getMeta: async (doctype: string) => {
- *   // fetch doctype meta from API
- *  },
+ *   router,
+ *   getMeta: async (routeContext) => {
+ *     // routeContext contains: { path, segments }
+ *     // fetch doctype meta from your API using the route context
+ *   },
+ *   autoInitializeRouter: true,
+ *   onRouterInitialized: async (registry, stonecrop) => {
+ *     // your custom initialization logic here
+ *   }
  * })
- *
  * app.mount('#app')
  * ```
- *
  * @public
  */
 const plugin: Plugin = {
 	install: (app: App, options?: InstallOptions) => {
-		// check if the router is already installed via another plugin
+		// Check for existing router installation
 		const existingRouter = app.config.globalProperties.$router
-		const appRouter = existingRouter || options?.router
-		const registry = new Registry(appRouter, options?.getMeta)
-
-		if (!existingRouter && appRouter) {
-			app.use(appRouter)
+		const providedRouter = options?.router
+		const router = existingRouter || providedRouter
+		if (!existingRouter && providedRouter) {
+			app.use(providedRouter)
 		}
 
-		app.use(pinia)
+		// Create registry with available router
+		const registry = new Registry(router, options?.getMeta)
 		app.provide('$registry', registry)
+		app.config.globalProperties.$registry = registry
+
+		// Create and provide a global Stonecrop instance
+		const stonecrop = new Stonecrop(registry)
+		app.provide('$stonecrop', stonecrop)
+		app.config.globalProperties.$stonecrop = stonecrop
+
+		// Initialize operation log store if Pinia is available
+		// This ensures the store is created with the app's Pinia instance
+		try {
+			const pinia = app.config.globalProperties.$pinia as Pinia | undefined
+			if (pinia) {
+				// Initialize the operation log store with the app's Pinia instance
+				const operationLogStore = useOperationLogStore(pinia)
+
+				// Provide the store so components can access it
+				app.provide('$operationLogStore', operationLogStore)
+				app.config.globalProperties.$operationLogStore = operationLogStore
+			}
+		} catch (error) {
+			// Pinia not available - operation log won't work, but app should still function
+			console.warn('Pinia not available - operation log features will be disabled:', error)
+		}
 
+		// Register custom components
 		if (options?.components) {
 			for (const [tag, component] of Object.entries(options.components)) {
 				app.component(tag, component)
 			}
 		}
+
+		// Setup auto-initialization if requested
+		if (options?.autoInitializeRouter && options.onRouterInitialized) {
+			void setupAutoInitialization(registry, stonecrop, options.onRouterInitialized)
+		}
 	},
 }
 

package/src/registry.ts

@@ -1,6 +1,8 @@
 import { Router } from 'vue-router'
 
 import DoctypeMeta from './doctype'
+import { getGlobalTriggerEngine } from './field-triggers'
+import { RouteContext } from './types/registry'
 
 /**
  * Stonecrop Registry class
@@ -31,7 +33,12 @@ export default class Registry {
 	 */
 	readonly router?: Router
 
-	constructor(router?: Router, getMeta?: (doctype: string) => DoctypeMeta | Promise<DoctypeMeta>) {
+	/**
+	 * Creates a new Registry instance (singleton pattern)
+	 * @param router - Optional Vue router instance for route management
+	 * @param getMeta - Optional function to fetch doctype metadata from an API
+	 */
+	constructor(router?: Router, getMeta?: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>) {
 		if (Registry._root) {
 			return Registry._root
 		}
@@ -43,10 +50,10 @@ export default class Registry {
 	}
 
 	/**
-	 * The getMeta function fetches doctype metadata from an API
+	 * The getMeta function fetches doctype metadata from an API based on route context
 	 * @see {@link DoctypeMeta}
 	 */
-	getMeta?: (doctype: string) => DoctypeMeta | Promise<DoctypeMeta>
+	getMeta?: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>
 
 	/**
 	 * Get doctype metadata
@@ -59,6 +66,14 @@ export default class Registry {
 			this.registry[doctype.slug] = doctype
 		}
 
+		// Register actions (including field triggers) with the field trigger engine
+		const triggerEngine = getGlobalTriggerEngine()
+		// Register under both doctype name and slug to handle different lookup patterns
+		triggerEngine.registerDoctypeActions(doctype.doctype, doctype.actions)
+		if (doctype.slug !== doctype.doctype) {
+			triggerEngine.registerDoctypeActions(doctype.slug, doctype.actions)
+		}
+
 		if (doctype.component && this.router && !this.router.hasRoute(doctype.doctype)) {
 			this.router.addRoute({
 				path: `/${doctype.slug}`,

package/src/stonecrop.ts

@@ -1,199 +1,290 @@
-import { createActor, createMachine } from 'xstate'
-
 import DoctypeMeta from './doctype'
-import { NotImplementedError } from './exceptions'
 import Registry from './registry'
-import { useDataStore } from './stores/data'
+import { createHST, type HSTNode } from './stores/hst'
+import { useOperationLogStore } from './stores/operation-log'
+import type { OperationLogConfig } from './types/operation-log'
+import type { RouteContext } from './types/registry'
 
 /**
- * Stonecrop class
+ * Main Stonecrop class with HST integration and built-in Operation Log
  * @public
  */
 export class Stonecrop {
+	private hstStore: HSTNode
+	private _operationLogStore?: ReturnType<typeof useOperationLogStore>
+	private _operationLogConfig?: Partial<OperationLogConfig>
+
+	/** The registry instance containing all doctype definitions */
+	readonly registry: Registry
+
 	/**
-	 * The root Stonecrop instance
+	 * Creates a new Stonecrop instance with HST integration
+	 * @param registry - The Registry instance containing doctype definitions
+	 * @param operationLogConfig - Optional configuration for the operation log
 	 */
-	static _root: Stonecrop
+	constructor(registry: Registry, operationLogConfig?: Partial<OperationLogConfig>) {
+		this.registry = registry
+
+		// Store config for lazy initialization
+		this._operationLogConfig = operationLogConfig
+
+		// Initialize HST store with auto-sync to Registry
+		this.initializeHSTStore()
+		this.setupRegistrySync()
+	}
 
 	/**
-	 * The name of the Stonecrop instance
-	 * @readonly
-	 *
-	 * @defaultValue 'Stonecrop'
+	 * Get the operation log store (lazy initialization)
+	 * @internal
 	 */
-	readonly name = 'Stonecrop'
+	getOperationLogStore() {
+		if (!this._operationLogStore) {
+			this._operationLogStore = useOperationLogStore()
+			if (this._operationLogConfig) {
+				this._operationLogStore.configure(this._operationLogConfig)
+			}
+		}
+		return this._operationLogStore
+	}
 
 	/**
-	 * The registry is an immutable collection of doctypes
-	 * @example
-	 * ```ts
-	 * {
-	 * 	'task': {
-	 * 		doctype: 'Task',
-	 * 		schema: {
-	 * 			title: 'string',
-	 * 			description: 'string',
-	 * 			...
-	 * 		}
-	 * 	},
-	 * 	...
-	 * }
-	 * ```
-	 * @see {@link Registry}
-	 * @see {@link DoctypeMeta}
+	 * Initialize the HST store structure
 	 */
-	readonly registry: Registry
+	private initializeHSTStore(): void {
+		const initialStoreStructure: Record<string, any> = {}
+
+		// Auto-populate from existing Registry doctypes
+		Object.keys(this.registry.registry).forEach(doctypeSlug => {
+			initialStoreStructure[doctypeSlug] = {}
+		})
+
+		this.hstStore = createHST(initialStoreStructure, 'StonecropStore')
+	}
+
+	/**
+	 * Setup automatic sync with Registry when doctypes are added
+	 */
+	private setupRegistrySync(): void {
+		// Extend Registry.addDoctype to auto-create HST store sections
+		const originalAddDoctype = this.registry.addDoctype.bind(this.registry)
+
+		this.registry.addDoctype = (doctype: DoctypeMeta) => {
+			// Call original method
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-call
+			originalAddDoctype(doctype)
+
+			// Auto-create HST store section for new doctype
+			if (!this.hstStore.has(doctype.slug)) {
+				this.hstStore.set(doctype.slug, {})
+			}
+		}
+	}
 
 	/**
-	 * The Pinia store that manages the mutable records
+	 * Get records hash for a doctype
+	 * @param doctype - The doctype to get records for
+	 * @returns HST node containing records hash
 	 */
-	store: ReturnType<typeof useDataStore>
+	records(doctype: string | DoctypeMeta): HSTNode {
+		const slug = typeof doctype === 'string' ? doctype : doctype.slug
+		this.ensureDoctypeExists(slug)
+		return this.hstStore.getNode(slug)
+	}
 
 	/**
-	 * @param registry - The immutable registry
-	 * @param store - The mutable Pinia store
-	 * @returns The Stonecrop instance with the given registry and store. If a Stonecrop instance has already been created, it returns the existing instance instead of creating a new one.
-	 * @example
-	 * ```ts
-	 * const registry = new Registry()
-	 * const store = useDataStore()
-	 * const stonecrop = new Stonecrop(registry, store)
-	 * ```
+	 * Add a record to the store
+	 * @param doctype - The doctype
+	 * @param recordId - The record ID
+	 * @param recordData - The record data
 	 */
-	constructor(registry: Registry, store: ReturnType<typeof useDataStore>) {
-		if (Stonecrop._root) {
-			return Stonecrop._root
+	addRecord(doctype: string | DoctypeMeta, recordId: string, recordData: any): void {
+		const slug = typeof doctype === 'string' ? doctype : doctype.slug
+
+		this.ensureDoctypeExists(slug)
+
+		// Store raw record data - let HST handle wrapping with proper hierarchy
+		this.hstStore.set(`${slug}.${recordId}`, recordData)
+	}
+
+	/**
+	 * Get a specific record
+	 * @param doctype - The doctype
+	 * @param recordId - The record ID
+	 * @returns HST node for the record or undefined
+	 */
+	getRecordById(doctype: string | DoctypeMeta, recordId: string): HSTNode | undefined {
+		const slug = typeof doctype === 'string' ? doctype : doctype.slug
+		this.ensureDoctypeExists(slug)
+
+		// First check if the record exists
+		const recordExists = this.hstStore.has(`${slug}.${recordId}`)
+		if (!recordExists) {
+			return undefined
 		}
-		Stonecrop._root = this
-		this.registry = registry
-		this.store = store
+
+		// Check if the actual value is undefined (i.e., record was removed)
+		const recordValue = this.hstStore.get(`${slug}.${recordId}`)
+		if (recordValue === undefined) {
+			return undefined
+		}
+
+		// Use getNode to get the properly wrapped HST node with correct parent relationships
+		return this.hstStore.getNode(`${slug}.${recordId}`)
 	}
 
 	/**
-	 * Sets up the Stonecrop instance with the given doctype
-	 * @param doctype - The doctype to setup
-	 * @example
-	 * ```ts
-	 * const doctype = await registry.getMeta('Task')
-	 * stonecrop.setup(doctype)
-	 * ```
+	 * Remove a record from the store
+	 * @param doctype - The doctype
+	 * @param recordId - The record ID
 	 */
-	setup(doctype: DoctypeMeta): void {
-		void this.getMeta(doctype.doctype)
+	removeRecord(doctype: string | DoctypeMeta, recordId: string): void {
+		const slug = typeof doctype === 'string' ? doctype : doctype.slug
+		this.ensureDoctypeExists(slug)
+
+		// Remove the specific record directly by setting to undefined
+		if (this.hstStore.has(`${slug}.${recordId}`)) {
+			this.hstStore.set(`${slug}.${recordId}`, undefined)
+		}
 	}
 
 	/**
-	 * Gets the meta for the given doctype
-	 * @param doctype - The doctype to get meta for
-	 * @returns The meta for the given doctype
-	 * @throws `NotImplementedError` if the `getMeta` function is not implemented for the doctype in the registry
-	 * @example
-	 * ```ts
-	 * const doctype = await registry.getMeta('Task')
-	 * const meta = stonecrop.getMeta(doctype)
-	 * ```
-	 * @see {@link DoctypeMeta}
+	 * Get all record IDs for a doctype
+	 * @param doctype - The doctype
+	 * @returns Array of record IDs
 	 */
-	async getMeta(doctype: string): Promise<DoctypeMeta> | never {
-		if (!this.registry.getMeta) {
-			throw new NotImplementedError(`getMeta function is not implemented for ${doctype} in the registry`)
+	getRecordIds(doctype: string | DoctypeMeta): string[] {
+		const slug = typeof doctype === 'string' ? doctype : doctype.slug
+		this.ensureDoctypeExists(slug)
+
+		const doctypeNode = this.hstStore.get(slug) as Record<string, any>
+		if (!doctypeNode || typeof doctypeNode !== 'object') {
+			return []
 		}
-		return await this.registry.getMeta(doctype)
+
+		return Object.keys(doctypeNode).filter(key => doctypeNode[key] !== undefined)
 	}
 
 	/**
-	 * Gets the records for the given doctype
-	 * @param doctype - The doctype to get records for
-	 * @param filters - The filters to apply to the records
-	 * @example
-	 * ```ts
-	 * const doctype = await registry.getMeta('Task')
-	 * await stonecrop.getRecords(doctype)
-	 * ```
-	 * @example
-	 * ```ts
-	 * const doctype = await registry.getMeta('Task')
-	 * const filters = JSON.stringify({ status: 'Open' })
-	 * await stonecrop.getRecords(doctype, { body: filters })
-	 * ```
-	 */
-	async getRecords(doctype: DoctypeMeta, filters?: RequestInit): Promise<void> {
-		this.store.$patch({ records: [] })
-		const records = await fetch(`/${doctype.slug}`, filters)
-		const data: Record<string, any>[] = await records.json()
-		this.store.$patch({ records: data })
-	}
-
-	/**
-	 * Gets the record for the given doctype and id
-	 * @param doctype - The doctype to get record for
-	 * @param id - The id of the record to get
-	 * @example
-	 * ```ts
-	 * const doctype = await registry.getMeta('Task')
-	 * await stonecrop.getRecord(doctype, 'TASK-00001')
-	 * ```
-	 */
-	async getRecord(doctype: DoctypeMeta, id: string): Promise<void> {
-		this.store.$patch({ record: {} })
-		const record = await fetch(`/${doctype.slug}/${id}`)
-		const data: Record<string, any> = await record.json()
-		this.store.$patch({ record: data })
-	}
-
-	/**
-	 * Runs the action for the given doctype and id
-	 * @param doctype - The doctype to run action for
+	 * Clear all records for a doctype
+	 * @param doctype - The doctype
+	 */
+	clearRecords(doctype: string | DoctypeMeta): void {
+		const slug = typeof doctype === 'string' ? doctype : doctype.slug
+		this.ensureDoctypeExists(slug)
+
+		// Get all record IDs and remove them
+		const recordIds = this.getRecordIds(slug)
+		recordIds.forEach(recordId => {
+			this.hstStore.set(`${slug}.${recordId}`, undefined)
+		})
+	}
+
+	/**
+	 * Setup method for doctype initialization
+	 * @param doctype - The doctype to setup
+	 */
+	setup(doctype: DoctypeMeta): void {
+		// Ensure doctype exists in store
+		this.ensureDoctypeExists(doctype.slug)
+	}
+
+	/**
+	 * Run action on doctype
+	 * Executes the action and logs it to the operation log for audit tracking
+	 * @param doctype - The doctype
 	 * @param action - The action to run
-	 * @param id - The id(s) of the record(s) to run action on
-	 * @example
-	 * ```ts
-	 * const doctype = await registry.getMeta('Task')
-	 * stonecrop.runAction(doctype, 'create')
-	 * ```
-	 * @example
-	 * ```ts
-	 * const doctype = await registry.getMeta('Task')
-	 * stonecrop.runAction(doctype, 'update', ['TASK-00001'])
-	 * ```
-	 * @example
-	 * ```ts
-	 * const doctype = await registry.getMeta('Task')
-	 * stonecrop.runAction(doctype, 'delete', ['TASK-00001'])
-	 * ```
-	 * @example
-	 * ```ts
-	 * const doctype = await registry.getMeta('Task')
-	 * stonecrop.runAction(doctype, 'merge', ['TASK-00001', 'TASK-00002'])
-	 * ```
-	 */
-	runAction(doctype: DoctypeMeta, action: string, id?: string[]): void {
+	 * @param args - Action arguments (typically record IDs)
+	 */
+	runAction(doctype: DoctypeMeta, action: string, args?: any[]): void {
 		const registry = this.registry.registry[doctype.slug]
-		const actions = registry.actions?.get(action)
-		const workflow = registry.workflow
+		const actions = registry?.actions?.get(action)
+		const recordIds = Array.isArray(args) ? args.filter((arg): arg is string => typeof arg === 'string') : undefined
 
-		// trigger the action on the state machine
-		if (workflow) {
-			const machine = createMachine(workflow)
-			const actor = createActor(machine)
+		// Log action execution start
+		const opLogStore = this.getOperationLogStore()
+		let actionResult: 'success' | 'failure' | 'pending' = 'success'
+		let actionError: string | undefined
 
-			// TODO: this shouldn't spawn an actor at the initial state always; look into persistence
-			actor.start()
-			actor.send({ type: action, id })
-
-			// run actions after state machine transition
-			// TODO: should this happen with or without the workflow?
+		try {
+			// Execute action functions
 			if (actions && actions.length > 0) {
-				actions.forEach(action => {
-					// TODO: Replace Function constructor with a safer action execution mechanism
-					// This is currently flagged as a security risk (implied eval)
-					// Consider using a registry of pre-defined action functions instead
-					// eslint-disable-next-line @typescript-eslint/no-implied-eval
-					const actionFn = new Function(action)
-					// eslint-disable-next-line @typescript-eslint/no-unsafe-call
-					actionFn(id)
+				actions.forEach(actionStr => {
+					try {
+						// eslint-disable-next-line @typescript-eslint/no-implied-eval
+						const actionFn = new Function('args', actionStr)
+						// eslint-disable-next-line @typescript-eslint/no-unsafe-call
+						actionFn(args)
+					} catch (error) {
+						actionResult = 'failure'
+						actionError = error instanceof Error ? error.message : 'Unknown error'
+						throw error
+					}
 				})
 			}
+		} catch {
+			// Error already set in inner catch
+		} finally {
+			// Log the action execution to operation log
+			opLogStore.logAction(doctype.doctype, action, recordIds, actionResult, actionError)
 		}
 	}
+
+	/**
+	 * Get records from server (maintains compatibility)
+	 * @param doctype - The doctype
+	 */
+	async getRecords(doctype: DoctypeMeta): Promise<void> {
+		const response = await fetch(`/${doctype.slug}`)
+		const records = await response.json()
+
+		// Store each record in HST
+		records.forEach((record: any) => {
+			if (record.id) {
+				this.addRecord(doctype, record.id, record)
+			}
+		})
+	}
+
+	/**
+	 * Get single record from server (maintains compatibility)
+	 * @param doctype - The doctype
+	 * @param recordId - The record ID
+	 */
+	async getRecord(doctype: DoctypeMeta, recordId: string): Promise<void> {
+		const response = await fetch(`/${doctype.slug}/${recordId}`)
+		const record = await response.json()
+
+		// Store record
+		this.addRecord(doctype, recordId, record)
+	}
+
+	/**
+	 * Ensure doctype section exists in HST store
+	 * @param slug - The doctype slug
+	 */
+	private ensureDoctypeExists(slug: string): void {
+		if (!this.hstStore.has(slug)) {
+			this.hstStore.set(slug, {})
+		}
+	}
+
+	/**
+	 * Get doctype metadata from the registry
+	 * @param context - The route context
+	 * @returns The doctype metadata
+	 */
+	async getMeta(context: RouteContext): Promise<any> {
+		if (!this.registry.getMeta) {
+			throw new Error('No getMeta function provided to Registry')
+		}
+		return await this.registry.getMeta(context)
+	}
+
+	/**
+	 * Get the root HST store node for advanced usage
+	 * @returns Root HST node
+	 */
+	getStore(): HSTNode {
+		return this.hstStore
+	}
 }