@stream44.studio/encapsulate 0.2.0-rc.1

package/src/encapsulate.ts

@@ -0,0 +1,662 @@
+
+type TSpineOptions = {
+    spineFilesystemRoot?: string,
+    spineContracts: Record<string, any>,
+    staticAnalyzer?: any,
+    timing?: { record: (step: string) => void, chalk?: any }
+}
+
+type TSpineRunOptions = {
+    overrides?: Record<string, any>,
+    options?: Record<string, any>
+}
+
+type TSpineRootsInvocationHandler = (context: { apis: Record<string, any>, capsules?: Record<string, any> }) => Promise<any>
+
+type TSpine = {
+    freeze: () => Promise<TSpineSnapshot>,
+    encapsulate: (definition: TCapsuleDefinition, options: TCapsuleOptions) => Promise<TCapsule>,
+    capsules: Record<string, any>
+}
+
+type TSpineSnapshot = {
+    capsules: Record<string, Record<string, any>>
+}
+
+type TSpineRuntime = {
+    run: (options: TSpineRunOptions, handler: TSpineRootsInvocationHandler) => Promise<any>
+}
+
+type TSpineRuntimeOptions = {
+    spineFilesystemRoot?: string,
+    spineContracts?: Record<string, any>,
+    snapshot?: TSpineSnapshot,
+    capsules?: Record<string, any>,
+    loadCapsule?: (options: { capsuleSourceLineRef: string, capsuleSnapshot: any, capsuleName?: string }) => Promise<any>
+}
+
+type TCapsuleSnapshot = {
+    cst: any,
+    spineContracts: Record<string, any>
+}
+
+type TCapsuleMakeInstanceOptions = {
+    overrides?: Record<string, any>,
+    options?: Record<string, any>,
+    runtimeSpineContracts?: Record<string, any>
+}
+
+type TCapsule = {
+    capsuleSourceLineRef: string,
+    definition: TCapsuleDefinition,
+    encapsulateOptions: TEncapsulateOptions,
+    cst?: any,
+    crt?: any,
+    makeInstance: (options?: TCapsuleMakeInstanceOptions) => any,
+    toCapsuleReference: () => { capsuleSourceLineRef: string, capsuleSourceNameRefHash: any }
+}
+
+// Spine contract URI -> Property contract name -> Property definitions
+// Property contracts can be empty {} (for struct markers) or contain property definitions
+type TCapsuleDefinition = Record<string, Record<string, {} | Record<string, { type: keyof typeof CapsulePropertyTypes, [key: string]: any }>>>
+
+type TCapsuleOptions = {
+    importMeta?: {
+        url: string
+    },
+    importStack?: string,
+    importStackLine?: number,
+    moduleFilepath?: string,
+    capsuleName?: string,
+    ambientReferences?: Record<string, any>,
+    cst?: any,
+    crt?: any
+}
+
+type TEncapsulateOptions = {
+    moduleFilepath: string,
+    importStackLine: number,
+    capsuleName?: string,
+    ambientReferences?: Record<string, any>,
+    capsuleSourceLineRef: string
+}
+
+type TSpineContext = {
+    spineOptions: TSpineOptions,
+    spineContracts: Record<string, any>,
+    capsules: Record<string, any>
+}
+
+
+export const CapsulePropertyTypes = {
+    Function: 'Function' as const,
+    GetterFunction: 'GetterFunction' as const,
+    String: 'String' as const,
+    Mapping: 'Mapping' as const,
+    Literal: 'Literal' as const,
+}
+
+// ##################################################
+// # Spine
+// ##################################################
+
+export async function SpineRuntime(options: TSpineRuntimeOptions): Promise<TSpineRuntime> {
+
+    const spineContracts = options.spineContracts || {}
+    const capsules: Record<string, any> = {}
+
+    const loadedCapsules: Record<string, any> = options.capsules || {}
+
+    const spine = {
+        run: async function (
+            runOptions: TSpineRunOptions,
+            handler: TSpineRootsInvocationHandler
+        ): Promise<any> {
+
+            const capsules: Record<string, any> = {}
+
+            const hydratedSnapshots: Record<string, any> = {}
+
+            // Ensure all capsules are hydrated.
+            await Promise.all(Object.entries(loadedCapsules).map(async ([capsuleSourceLineRef, capsule]) => {
+
+                const hydratedSnapshot = options.snapshot?.capsules?.[capsuleSourceLineRef]
+                if (!hydratedSnapshot) return
+
+                await Promise.all(Object.entries(hydratedSnapshot.spineContracts).map(async ([spineContractUri, capsuleContractSnapshot]) => {
+                    hydratedSnapshot.spineContracts[spineContractUri] = spineContracts[spineContractUri].hydrate({
+                        capsuleSnapshot: capsuleContractSnapshot
+                    })
+                }))
+
+                hydratedSnapshots[capsuleSourceLineRef] = hydratedSnapshot
+                if (capsule.encapsulateOptions.capsuleName) {
+                    hydratedSnapshots[capsule.encapsulateOptions.capsuleName] = hydratedSnapshot
+                }
+            }))
+
+            // Extract only the spine contract properties from hydrated snapshots
+            const hydratedOverrides: Record<string, any> = {}
+            for (const [capsuleRef, snapshot] of Object.entries(hydratedSnapshots)) {
+                if (snapshot.spineContracts) {
+                    // Merge all spine contract properties into a single object for this capsule
+                    const capsuleOverrides: Record<string, any> = {}
+                    for (const [spineContractUri, spineContractData] of Object.entries(snapshot.spineContracts)) {
+                        Object.assign(capsuleOverrides, spineContractData)
+                    }
+                    hydratedOverrides[capsuleRef] = capsuleOverrides
+                }
+            }
+
+            const overrides = merge(
+                hydratedOverrides,
+                runOptions.overrides || {}
+            )
+
+            // Helper function to create a proxy that dynamically unwraps .api layers
+            function createUnwrappingProxy(obj: any): any {
+                if (!obj || typeof obj !== 'object') return obj
+
+                // If this object has an .api property, create a proxy for it
+                if (obj.api && typeof obj.api === 'object') {
+                    return new Proxy(obj.api, {
+                        get: (target: any, prop: string | symbol) => {
+                            if (typeof prop === 'symbol') return target[prop]
+
+                            let value = target[prop]
+
+                            // If the value is a Proxy (from Membrane), get the actual value through it
+                            // The Proxy will return the correct value from its get trap
+                            if (value && typeof value === 'object') {
+                                // Check if this value has .api - if so, unwrap it
+                                if (value.api && typeof value.api === 'object') {
+                                    return createUnwrappingProxy(value)
+                                }
+                            }
+
+                            return value
+                        }
+                    })
+                }
+
+                return obj
+            }
+
+            const apis: Record<string, any> = {}
+
+            // Group keys by capsule object to avoid duplicate processing
+            const capsuleToKeys = new Map<any, string[]>()
+            for (const [key, capsule] of Object.entries(loadedCapsules)) {
+                if (!capsuleToKeys.has(capsule)) {
+                    capsuleToKeys.set(capsule, [])
+                }
+                capsuleToKeys.get(capsule)!.push(key)
+            }
+
+            // Instantiate each unique capsule once
+            for (const [capsule, keys] of capsuleToKeys) {
+                const instance = await capsule.makeInstance({
+                    overrides,
+                    options: runOptions.options?.[keys[0]],
+                    runtimeSpineContracts: spineContracts
+                })
+
+                // Register instance under all keys that reference this capsule
+                for (const key of keys) {
+                    capsules[key] = {
+                        capsule,
+                        instance,
+                        makeInstance: undefined
+                    }
+
+                    // Create proxy that dynamically unwraps .api layers
+                    apis[key] = createUnwrappingProxy(instance)
+                }
+            }
+
+            const result = await handler({ apis, capsules })
+
+            return result
+        },
+
+        encapsulate: async function (definition: TCapsuleDefinition, encapsulateOptions: TCapsuleOptions): Promise<TCapsule> {
+
+            return encapsulate(definition, encapsulateOptions, {
+                spineOptions: {
+                    spineFilesystemRoot: options.spineFilesystemRoot,
+                    spineContracts,
+                    staticAnalyzer: (options as any).staticAnalyzer
+                },
+                spineContracts,
+                capsules
+            })
+        }
+    }
+
+    if (options.snapshot) {
+
+        await Promise.all(Object.entries(options.snapshot.capsules).map(async ([capsuleSourceLineRef, capsuleSnapshot]) => {
+
+            if (typeof loadedCapsules[capsuleSourceLineRef] !== 'undefined') return
+
+            // Extract capsuleName from snapshot if available
+            const capsuleName = capsuleSnapshot?.spineContracts?.['#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0']?.['#@stream44.studio/encapsulate/structs/Capsule.v0']?.capsuleName
+
+            const capsule = await options.loadCapsule!({
+                capsuleSourceLineRef,
+                capsuleSnapshot,
+                capsuleName
+            })
+
+            loadedCapsules[capsuleSourceLineRef] = await capsule({
+                encapsulate: spine.encapsulate,
+                CapsulePropertyTypes,
+                makeImportStack,
+                loadCapsule: options.loadCapsule
+            })
+        }))
+    }
+
+    return spine
+}
+
+export async function Spine(options: TSpineOptions): Promise<TSpine> {
+
+    const spineOptions = options
+
+    options.timing?.record('Spine: Initialized')
+
+    if (typeof spineOptions.spineFilesystemRoot === 'undefined') throw new Error(`'spineFilesystemRoot' not defined!`)
+    if (typeof spineOptions.spineContracts === 'undefined') throw new Error(`'spineContracts' not defined!`)
+
+    const spineContracts = spineOptions.spineContracts
+    const capsules: Record<string, any> = {}
+
+    options.timing?.record('Spine: Ready to encapsulate')
+
+    return {
+        capsules,
+        freeze: async function (): Promise<TSpineSnapshot> {
+
+            options.timing?.record('Spine: Starting freeze')
+
+            const snapshot: TSpineSnapshot = {
+                capsules: {}
+            }
+
+            options.timing?.record(`Spine: Freezing ${Object.keys(capsules).length} capsules`)
+
+            await Promise.all(Object.entries(capsules).map(async ([capsuleSourceLineRef, capsule]) => {
+
+                if (!capsule.cst.source.capsuleName) throw new Error(`'capsuleName' must be set for encapsulate options to enable freezing.`)
+
+                snapshot.capsules[capsuleSourceLineRef] = {
+                    cst: capsule.cst,
+                    spineContracts: {}
+                }
+
+                const { spineContractCapsuleInstances } = await capsule.makeInstance()
+
+                await Promise.all(Object.entries(spineContractCapsuleInstances).map(async ([spineContractUri, spineContractCapsuleInstance]) => {
+
+                    snapshot.capsules[capsuleSourceLineRef] = merge(
+                        snapshot.capsules[capsuleSourceLineRef],
+                        await (spineContractCapsuleInstance as any).freeze({
+                            spineContractUri,
+                            capsule
+                        })
+                    )
+                }))
+            }))
+
+            options.timing?.record('Spine: Freeze complete')
+
+            // console.log('snapshot:', JSON.stringify(snapshot, null, 4))
+            return snapshot
+        },
+
+        encapsulate: async function (definition: TCapsuleDefinition, options: TCapsuleOptions): Promise<TCapsule> {
+
+            return encapsulate(definition, options, {
+                spineOptions,
+                spineContracts,
+                capsules
+            })
+        }
+    }
+}
+
+
+
+
+// ##################################################
+// # Encapsulate
+// ##################################################
+
+async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOptions, spine: TSpineContext): Promise<TCapsule> {
+
+    if (!options.importMeta && !options.moduleFilepath) throw new Error(`'options.importMeta' nor 'options.moduleFilepath' not specified!`)
+    if (!options.importStack && !options.importStackLine) throw new Error(`'options.importStack' nor 'options.importStackLine' specified!`)
+
+    const moduleFilepath = options.moduleFilepath || relative(spine.spineOptions.spineFilesystemRoot || '', options.importMeta!.url.replace(/^file:\/\//, ''))
+    const importStackLine = options.importStackLine || formatImportStackFrame(options.importStack!)
+
+    if (typeof importStackLine !== 'number') throw new Error(`Could not determine importStackLine from options`)
+
+    const encapsulateOptions: TEncapsulateOptions = {
+        moduleFilepath,
+        importStackLine,
+        capsuleName: options.capsuleName,
+        ambientReferences: options.ambientReferences,
+        capsuleSourceLineRef: `${moduleFilepath}:${importStackLine}`
+    }
+
+    spine.spineOptions.timing?.record(`Encapsulate: Start for ${moduleFilepath}`)
+
+    const { csts, crts } = await spine.spineOptions.staticAnalyzer?.parseModule({
+        spineOptions: spine.spineOptions,
+        encapsulateOptions
+    }) || {
+        csts: options.cst ? { [encapsulateOptions.capsuleSourceLineRef]: options.cst } : undefined,
+        crts: options.crt ? { [encapsulateOptions.capsuleSourceLineRef]: options.crt } : undefined
+    }
+
+    const defaultInstance: Record<string, any> = {}
+
+    // Cache for instances to prevent duplicate makeInstance calls
+    const instanceCache = new Map<string, Promise<any>>()
+
+    const capsule: TCapsule = {
+        toCapsuleReference: () => {
+            return {
+                capsuleSourceLineRef: encapsulateOptions.capsuleSourceLineRef,
+                capsuleSourceNameRefHash: capsule.cst.capsuleSourceNameRefHash,
+            }
+        },
+        capsuleSourceLineRef: encapsulateOptions.capsuleSourceLineRef,
+        definition,
+        encapsulateOptions,
+        cst: csts?.[encapsulateOptions.capsuleSourceLineRef],
+        crt: crts?.[encapsulateOptions.capsuleSourceLineRef],
+        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts }: TCapsuleMakeInstanceOptions = {}) => {
+
+            // Create cache key based on parameters
+            const cacheKey = JSON.stringify({
+                overrides,
+                options,
+                hasRuntimeContracts: !!runtimeSpineContracts
+            })
+
+            // Check if we already have a pending or completed instance creation
+            if (instanceCache.has(cacheKey)) {
+                return instanceCache.get(cacheKey)!
+            }
+
+            // Create the instance promise and cache it immediately
+            const instancePromise = (async () => {
+                const encapsulatedApi: Record<string, any> = {}
+                const spineContractCapsuleInstances: Record<string, any> = {}
+
+                const capsuleInstance = {
+                    api: encapsulatedApi,
+                    spineContractCapsuleInstances
+                }
+
+                // Property contracts are keys starting with '#' that contain nested properties
+                // Structure: spineContractUri -> propertyContractUri -> propertyName -> propertyDef
+                const propertyContractDefinitions: Record<string, Record<string, Record<string, any>>> = {}
+                // Track which property contracts are defined for validation
+                const definedPropertyContracts = new Set<string>()
+
+                for (const [spineContractUri, propertyDefinitions] of Object.entries(definition)) {
+                    // Validate that at least one property contract key exists
+                    const hasPropertyContract = Object.keys(propertyDefinitions).some(key => key.startsWith('#'))
+                    if (!hasPropertyContract) {
+                        throw new Error(`Spine contract '${spineContractUri}' for capsule '${capsule.capsuleSourceLineRef}' must specify at least one property contract layer using a key starting with '#'. For example: '#': { ...properties }`)
+                    }
+
+                    propertyContractDefinitions[spineContractUri] = {}
+
+                    for (const [propContractUri, propDef] of Object.entries(propertyDefinitions)) {
+                        if (propContractUri.startsWith('#')) {
+
+                            // This is a property contract - store its properties (merge if it already exists)
+                            if (!propertyContractDefinitions[spineContractUri][propContractUri]) {
+                                propertyContractDefinitions[spineContractUri][propContractUri] = {}
+                            }
+                            Object.assign(propertyContractDefinitions[spineContractUri][propContractUri], propDef as Record<string, any>)
+                            definedPropertyContracts.add(propContractUri)
+
+                            // If this is a non-default property contract, add a dynamic mapping to the '#' contract
+                            if (propContractUri !== '#') {
+                                // We have a property contract URI we need to resolve and load
+                                // Add a dynamic property mapping for this contract to the '#' group
+                                const contractKey = '#' + propContractUri.substring(1)
+
+                                if (!propertyContractDefinitions[spineContractUri]['#']) {
+                                    propertyContractDefinitions[spineContractUri]['#'] = {}
+                                }
+
+                                propertyContractDefinitions[spineContractUri]['#'][contractKey] = {
+                                    type: CapsulePropertyTypes.Mapping,
+                                    value: propContractUri.substring(1),
+                                    propertyContractDelegate: propContractUri
+                                }
+                            }
+
+                        } else {
+                            throw new Error(`Property '${propContractUri}' in spine contract '${spineContractUri}' for capsule '${capsule.capsuleSourceLineRef}' must be nested under a property contract uri starting with '#'. For example: '#': { ${propContractUri}: {...} }`)
+                        }
+                    }
+                }
+
+                // Merge overrides and options by property contract
+                // Structure: propertyContractUri -> propertyName -> value
+                const mergedValuesByContract: Record<string, Record<string, any>> = {}
+
+                // Helper to validate and merge values from a source (overrides or options)
+                const mergeByContract = (source: any, sourceName: string) => {
+                    if (!source) return
+
+                    for (const [propertyContractUri, properties] of Object.entries(source)) {
+                        if (!propertyContractUri.startsWith('#')) {
+                            throw new Error(`${sourceName} for capsule '${capsule.capsuleSourceLineRef}' must use property contract keys starting with '#'. Found key: '${propertyContractUri}'`)
+                        }
+
+                        if (!definedPropertyContracts.has(propertyContractUri)) {
+                            throw new Error(`${sourceName} for capsule '${capsule.capsuleSourceLineRef}' references property contract '${propertyContractUri}' which is not defined on the capsule`)
+                        }
+
+                        if (!mergedValuesByContract[propertyContractUri]) {
+                            mergedValuesByContract[propertyContractUri] = {}
+                        }
+
+                        Object.assign(mergedValuesByContract[propertyContractUri], properties)
+                    }
+                }
+
+                // Merge in order: overrides by lineRef, overrides by name, options
+                mergeByContract(overrides?.[encapsulateOptions.capsuleSourceLineRef], 'Overrides')
+                if (encapsulateOptions.capsuleName) {
+                    mergeByContract(overrides?.[encapsulateOptions.capsuleName], 'Overrides')
+                }
+                mergeByContract(options, 'Options')
+
+                // Create a single shared self for all spine contracts by flattening merged values
+                const self = merge(
+                    {},
+                    defaultInstance,
+                    ...Object.values(mergedValuesByContract)
+                )
+
+                // Use runtime spine contracts if provided, otherwise fall back to encapsulation spine contracts
+                const activeSpineContracts = runtimeSpineContracts || spine.spineContracts
+
+                for (const [spineContractUri, propertyContracts] of Object.entries(propertyContractDefinitions)) {
+
+                    const spineContract = activeSpineContracts[spineContractUri] as any
+
+                    if (!spineContract) throw new Error(`Contract uri '${spineContractUri}' used by capsule not available in Spine!`)
+
+                    const spineContractCapsuleInstance = spineContract.makeContractCapsuleInstance({
+                        spineContractUri,
+                        encapsulateOptions,
+                        capsuleInstance,
+                        self,
+                        capsule,
+                        encapsulatedApi,
+                        runtimeSpineContracts
+                    })
+
+                    spineContractCapsuleInstances[spineContractUri] = spineContractCapsuleInstance
+
+                    // Iterate through each property contract within this spine contract
+                    for (const [propertyContractUri, properties] of Object.entries(propertyContracts)) {
+                        // Skip non-'#' property contracts as they're already accessible via dynamic mappings in '#'
+                        if (propertyContractUri !== '#') {
+                            continue
+                        }
+                        for (const [propertyName, propertyDefinition] of Object.entries(properties)) {
+
+                            if (!propertyDefinition.type || !(propertyDefinition.type in CapsulePropertyTypes)) throw new Error(`Type '${propertyDefinition.type}' for property '${propertyName}' on spineContract '${spineContractUri}' not set or supported!`)
+
+                            await spineContractCapsuleInstance.mapProperty({
+                                overrides,
+                                options,
+                                property: {
+                                    name: propertyName,
+                                    definition: propertyDefinition,
+                                    propertyContractUri
+                                }
+                            })
+                        }
+                    }
+                }
+
+                return capsuleInstance
+            })()
+
+            // Cache the promise
+            instanceCache.set(cacheKey, instancePromise)
+
+            return instancePromise
+        }
+    }
+
+    spine.capsules[encapsulateOptions.capsuleSourceLineRef] = capsule
+    if (encapsulateOptions.capsuleName) {
+        spine.capsules[encapsulateOptions.capsuleName] = capsule
+    }
+
+    spine.spineOptions.timing?.record(`Encapsulate: Complete for ${moduleFilepath}`)
+
+    return capsule
+}
+
+
+
+function formatImportStackFrame(importStack: string): number | undefined {
+    const stackLines = importStack.split('\n')
+
+    const hasMakeImportStackMarker = importStack.includes('encapsulate:makeImportStack')
+    const targetMatchCount = hasMakeImportStackMarker ? 2 : 1
+
+    let matchCount = 0
+    for (let i = 0; i < stackLines.length; i++) {
+        const line = stackLines[i]
+
+        if (line.includes('encapsulate:makeImportStack')) {
+            continue
+        }
+
+        const match = line.match(/\(([^)]+):([0-9]+):[0-9]+\)|at ([^(]+):([0-9]+):[0-9]+/)
+        if (match) {
+            matchCount++
+            if (matchCount === targetMatchCount) {
+                const lineNumber = parseInt(match[2] || match[4])
+                return lineNumber
+            }
+        }
+    }
+
+    return undefined
+}
+
+// ##################################################
+// # Utilities
+// ##################################################
+
+export function makeImportStack() {
+    return new Error('encapsulate:makeImportStack').stack
+}
+
+export function join(...paths: string[]): string {
+    if (paths.length === 0) return '.'
+
+    let joined = paths.join('/')
+
+    const isAbsolute = joined.startsWith('/')
+    const parts: string[] = []
+
+    for (const part of joined.split('/')) {
+        if (part === '' || part === '.') continue
+        if (part === '..') {
+            if (parts.length > 0 && parts[parts.length - 1] !== '..') {
+                parts.pop()
+            } else if (!isAbsolute) {
+                parts.push('..')
+            }
+        } else {
+            parts.push(part)
+        }
+    }
+
+    let result = parts.join('/')
+    if (isAbsolute) result = '/' + result
+
+    return result || (isAbsolute ? '/' : '.')
+}
+
+function relative(from: string, to: string): string {
+    const fromParts = from.split('/').filter(p => p && p !== '.')
+    const toParts = to.split('/').filter(p => p && p !== '.')
+
+    let commonLength = 0
+    const minLength = Math.min(fromParts.length, toParts.length)
+
+    for (let i = 0; i < minLength; i++) {
+        if (fromParts[i] === toParts[i]) {
+            commonLength++
+        } else {
+            break
+        }
+    }
+
+    const upCount = fromParts.length - commonLength
+    const remainingTo = toParts.slice(commonLength)
+
+    const result = [...Array(upCount).fill('..'), ...remainingTo].join('/')
+    return result || '.'
+}
+
+function isObject(item: any): boolean {
+    return item && typeof item === 'object' && !Array.isArray(item)
+}
+
+export function merge<T = any>(target: T, ...sources: any[]): T {
+    if (!sources.length) return target
+    const source = sources.shift()
+
+    if (isObject(target) && isObject(source)) {
+        for (const key in source) {
+            if (isObject(source[key])) {
+                if (!target[key as keyof T]) Object.assign(target, { [key]: {} })
+                merge(target[key as keyof T], source[key])
+            } else {
+                Object.assign(target, { [key]: source[key] })
+            }
+        }
+    }
+
+    return merge(target, ...sources)
+}