@iebh/tera-fy 2.0.21 → 2.2.0

package/lib/syncro/entities.ts

@@ -0,0 +1,288 @@
+// @ts-ignore
+import Reflib from '@iebh/reflib';
+import {v4 as uuid4} from 'uuid';
+import {nanoid} from 'nanoid';
+import { BoundSupabaseyFunction } from '@iebh/supabasey';
+
+// DATABASE TABLE TYPE DEFINITIONS {{{
+interface ProjectRow {
+  data: {
+		temp?: { [key: string]: any };
+		// TODO: add other properties in project data
+	};
+	// TODO: Define other columns in project table
+}
+
+interface UserRow {
+	id: string;
+	data: {
+		id: string;
+		credits: number;
+		[key: string]: any;
+		// TODO: add other properties in user data
+	};
+	// TODO: Define other columns in user table
+}
+
+interface NamespaceRow {
+	project: string;
+	name: string;
+	data: {
+		[key: string]: any;
+		// TODO: add other properties in namespace data
+	};
+	// TODO: Define other namespace in user table
+}
+// }}}
+
+// Interface for each syncroconfic
+interface SyncroEntityConfig {
+	singular: string;
+	initState: (args: {
+			supabasey: BoundSupabaseyFunction;
+			id: string; // Primary ID for the entity
+			relation?: string; // Optional relation identifier (for namespaces, libraries)
+	}) => Promise<any>;
+
+	flushState: (args: {
+			supabasey: BoundSupabaseyFunction;
+			state: any; // The state object to flush
+			id?: string; // Primary ID (used in some lookups like namespaces)
+			fsId?: string; // ID often passed to Supabase RPCs (might be same as 'id')
+			relation?: string; // Optional relation identifier
+	}) => Promise<any>; // Return type signifies completion/result of flush
+}
+
+type SyncroConfig = Record<string, SyncroEntityConfig>;
+
+/**
+* Entities we support Syncro paths for, each should correspond directly with a Firebase/Firestore collection name
+*
+* @type {Object} An object lookup of entities
+*
+* @property {String} singular The singular noun for the item
+* @property {Function} initState Function called to initialize state when Firestore has no existing document. Called as `({supabase:BoundSupabaseyFunction, entity:String, id:String, relation?:string})` and expected to return the initial data object state
+* @property {Function} flushState Function called to flush state from Firebase to Supabase. Called the same as `initState` + `{state:Object}`
+*/
+const syncroConfig: SyncroConfig = {
+	projects: { // {{{
+		singular: 'project',
+		async initState({supabasey, id}) {
+			let projectData = await supabasey((supabase) => supabase
+				.from('projects')
+				.select('data')
+				.eq('id', id)
+				.maybeSingle<ProjectRow>()
+			);
+			if (!projectData) throw new Error(`Syncro project "${id}" not found`);
+			let data = projectData.data;
+
+			// MIGRATION - Move data.temp{} into Supabase files + add pointer to filename {{{
+			if (
+				data.temp // Project contains temp subkey
+				&& Object.values(data.temp).some((t: any) => typeof t == 'object') // Some of the temp keys are objects
+			) {
+				console.log('[MIGRATION] tera-fy project v1 -> v2', data.temp);
+				const tempObject = data.temp;
+
+				await Promise.all(
+					Object.entries(data.temp)
+						.filter(([, branch]) => typeof branch == 'object')
+						.map(([toolKey, ]) => {
+							console.log(`[MIGRATION] Converting data.temp[${toolKey}]...`);
+
+							const toolName = toolKey.split('-')[0];
+							const fileName = `data-${toolName}-${nanoid()}.json`;
+							console.log('[MIGRATION] Creating filename:', fileName);
+
+							return Promise.resolve()
+								.then(()=> supabasey((supabase) => supabase // Split data.temp[toolKey] -> file {{{
+									.storage
+									.from('projects')
+									.upload(
+										`${id}/${fileName}`,
+										new File(
+											[
+												new Blob(
+													[
+														JSON.stringify(tempObject[toolKey], null, '\t'),
+													],
+													{
+														type: 'application/json',
+													},
+												),
+											],
+											fileName,
+											{
+												type: 'application/json',
+											},
+										),
+										{
+											cacheControl: '3600',
+											upsert: true,
+										},
+									)
+								)) // }}}
+								.then(()=> tempObject[toolKey] = fileName) // Replace data.temp[toolKey] with new filename
+								.catch(e => {
+									console.warn('[MIGRATION] Failed to create file', fileName, '-', e);
+									throw e;
+								})
+
+						})
+				);
+			} // }}}
+
+			return data;
+		},
+		flushState({supabasey, state, fsId}) {
+			// Import Supabasey because 'supabasey' lowercase is just a function
+			return supabasey(supabase => supabase.rpc('syncro_merge_data', {
+				table_name: 'projects',
+				entity_id: fsId,
+				new_data: state,
+			}));
+		},
+	}, // }}}
+	project_libraries: { // {{{
+		singular: 'project library',
+		async initState({supabasey, id, relation}) {
+			if (!relation || !/_\*$/.test(relation)) throw new Error('Project library relation missing, path should resemble "project_library::${PROJECT}::${LIBRARY_FILE_ID}_*"');
+
+			let fileId = relation.replace(/_\*$/, '');
+
+			const files = await supabasey((supabase) => supabase
+				.storage
+				.from('projects')
+				.list(id))
+
+			const file = files?.find((f: any) => f.id == fileId);
+			if (!file) return Promise.reject(`Invalid file ID "${fileId}"`);
+
+			const blob = await supabasey((supabase) => supabase
+				.storage
+				.from('projects')
+				.download(`${id}/${file.name}`))
+
+			if (!blob) throw new Error('Failed to download file blob');
+
+			const refs = await Reflib.uploadFile({
+				file: new File(
+					[blob],
+					file.name.replace(/^.*[/\\]/, ''), // Extract basename from original file name
+				),
+			})
+
+			return Object.fromEntries(refs // Transform Reflib Ref array into a keyed UUID object
+				.map((ref: any) => [ // Construct Object.fromEntries() compatible object [key, val] tuple
+					uuid4(), // TODO: This should really be using V5 with some-kind of namespacing but I can't get my head around the documentation - MC 2025-02-21
+					ref, // The actual ref payload
+				])
+			)
+		},
+		flushState() {
+			throw new Error('Flushing project_libraries::* namespace is not yet supported');
+		},
+	}, // }}}
+	project_namespaces: { // {{{
+		singular: 'project namespace',
+		async initState({supabasey, id, relation}) {
+			if (!relation) throw new Error('Project namespace relation missing, path should resemble "project_namespaces::${PROJECT}::${RELATION}"');
+			let rows = await supabasey((supabase) => supabase
+				.from('project_namespaces')
+				.select('data')
+				.eq('project', id)
+				.eq('name', relation)
+				.limit(1)
+			);
+
+			if (rows && rows.length == 1) {
+				return rows[0].data;
+			} else {
+				const newItem = await supabasey((supabase) => supabase
+					.from('project_namespaces') // Doesn't exist - create it
+					.insert<NamespaceRow>({
+						project: id,
+						name: relation,
+						data: {},
+					})
+					.select('data')
+					.single<NamespaceRow>() // Assuming insert returns the single inserted row
+				);
+
+				if (!newItem) throw new Error('Failed to create project namespace');
+				return newItem.data;
+			}
+		},
+		flushState({supabasey, state, id, relation}) {
+			return supabasey((supabase) => supabase
+				.from('project_namespaces')
+				.update({
+					edited_at: new Date().toISOString(),
+					data: state,
+				})
+				.eq('project', id)
+				.eq('name', relation)
+			);
+		},
+	}, // }}}
+	test: { // {{{
+		singular: 'test',
+		async initState({supabasey, id}: {supabasey: BoundSupabaseyFunction, id: string}) {
+			let rows = await supabasey((supabase) => supabase
+				.from('test')
+				.select('data')
+				.eq('id', id)
+				.limit(1)
+			);
+
+			if (!rows || rows.length !== 1) return Promise.reject(`Syncro test item "${id}" not found`);
+			return rows[0].data;
+		},
+		flushState({supabasey, state, fsId}) {
+			return supabasey(supabase => supabase.rpc('syncro_merge_data', {
+				table_name: 'test',
+				entity_id: fsId,
+				new_data: state,
+			}));
+		},
+	}, // }}}
+	users: { // {{{
+		singular: 'user',
+		async initState({supabasey, id}: {supabasey: BoundSupabaseyFunction, id: string}) {
+			let user = await supabasey((supabase) => supabase
+				.from('users')
+				.select('data')
+				.eq('id', id)
+				.maybeSingle<UserRow>()
+			);
+			if (user) return user.data; // User is valid and already exists
+
+			// User row doesn't already exist - need to create stub
+			let newUser = await supabasey((supabase) => supabase
+				.from('users')
+				.insert<UserRow>({
+					id,
+					data: {
+						id,
+						credits: 1000,
+					},
+				})
+				.select('data')
+				.single<UserRow>() // Assuming insert returns the single inserted row
+			);
+			if (!newUser) throw new Error('Failed to create user');
+			return newUser.data; // Return back the data that eventually got created - allowing for database triggers, default field values etc.
+
+		},
+		flushState({supabasey, state, fsId}) {
+			return supabasey(supabase => supabase.rpc('syncro_merge_data', {
+				table_name: 'users',
+				entity_id: fsId,
+				new_data: state,
+			}));
+		},
+	}, // }}}
+};
+
+export default syncroConfig;

package/lib/syncro/{keyed.js → keyed.ts}

@@ -3,6 +3,20 @@ import {doc as FirestoreDocRef, getDoc as FirestoreGetDoc} from 'firebase/firest
 import Syncro from './syncro.js';
 import SyncroEntities from './entities.js';
 
+// Define a basic structure for what pathSplit should return
+interface PathSplitResult {
+	entity: string;
+	id: string;
+	relation?: string; // Making relation optional
+	fsCollection: string;
+	fsId: string;
+}
+
+// Define a structure for options passed to flush
+interface FlushOptions {
+	destroy?: boolean;
+}
+
 /**
 * @class SyncroKeyed
 * TERA Isomorphic SyncroKeyed class
@@ -27,7 +41,7 @@ export default class SyncroKeyed extends Syncro {
 	* Various storage about keyed path
 	*/
 	keyedPath = {
-		getKey(path, index) {
+		getKey(path: string, index: number): string {
 			return path + '_' + index;
 		},
 	};
@@ -38,7 +52,7 @@ export default class SyncroKeyed extends Syncro {
 	*
 	* @type {Array<Syncro>}
 	*/
-	members = [];
+	members: Syncro[] = [];
 
 
 	/**
@@ -47,13 +61,13 @@ export default class SyncroKeyed extends Syncro {
 	* @param {String} path Mount path for the Syncro. Should be in the form `${ENTITY}::${ID}(::${RELATION})?_*` (must contain a '*' operator)
 	* @param {Object} [options] Additional instance setters (mutates instance directly)
 	*/
-	constructor(path, options) {
+	constructor(path: string, options?: Record<string, any>) {
 		super(path, options);
 
 		if (!/\*/.test(path)) throw new Error('SyncroKeyed paths must contain at least one asterisk as an object pagination indicator');
 
-		let {prefix, suffix} = /^(?<prefix>.+)\*(?<suffix>.*)$/.exec(path).groups;
-		this.keyedPath.getKey = (path, index) => `${prefix}${index}${suffix}`;
+		let {prefix, suffix} = /^(?<prefix>.+)\*(?<suffix>.*)$/.exec(path)!.groups!;
+		this.keyedPath.getKey = (path: string, index: number): string => `${prefix}${index}${suffix}`;
 	}
 
 
@@ -62,7 +76,7 @@ export default class SyncroKeyed extends Syncro {
 	*
 	* @returns {Promise} A promise which resolves when the operation has completed
 	*/
-	async destroy() {
+	async destroy(): Promise<never[]> { // Match base class signature
 		this.debug('Destroy!');
 		await Promise.all(
 			this.members.map(member =>
@@ -71,6 +85,7 @@ export default class SyncroKeyed extends Syncro {
 		);
 
 		this.members = [];
+		return [] as never[]; // Return empty array cast to never[] to satisfy signature
 	}
 
 
@@ -80,14 +95,15 @@ export default class SyncroKeyed extends Syncro {
 	*
 	* @returns {Promise<Syncro>} A promise which resolves as this SyncroKeyed instance when completed
 	*/
-	mount() {
-		let {entity, id, relation, fsCollection, fsId} = Syncro.pathSplit(this.path, {allowAsterisk: true});
+	mount(): Promise<Syncro> {
+		// Cast the result to the expected interface
+		let {entity, id, relation, fsCollection, fsId} = Syncro.pathSplit(this.path, {allowAsterisk: true}) as PathSplitResult;
 
 		return Promise.resolve()
-			.then(()=> new Promise(resolve => { // Mount all members by looking for similar keys
+			.then(()=> new Promise<void>(resolve => { // Mount all members by looking for similar keys
 				this.members = []; // Reset member list
 
-				let seekMember = async (index) => {
+				let seekMember = async (index: number) => {
 					let memberId = fsId.replace('*', ''+index);
 					this.debug('Seek keyedMember', fsCollection, '#', memberId);
 
@@ -96,7 +112,7 @@ export default class SyncroKeyed extends Syncro {
 					let doc = await FirestoreGetDoc(docRef);
 					if (doc.exists()) { // Found a matching entry
 						// Expand member lookup with the new member by its numeric index
-						this.keyedMembersExpand(index);
+						await this.keyedMembersExpand(index);
 
 						// Queue up next member fetcher
 						setTimeout(()=> seekMember(index+1));
@@ -116,19 +132,21 @@ export default class SyncroKeyed extends Syncro {
 				this.debug('Populate initial SyncroKeyed state');
 
 				// Extract base data + add document and return new hook
-				if (!SyncroEntities[entity]) throw new Error(`Unknown Sync entity "${entity}"`);
+				const entityKey = entity as keyof typeof SyncroEntities;
+				if (!SyncroEntities[entityKey]) throw new Error(`Unknown Sync entity "${entity}"`);
 
 				// Go fetch the initial state object
-				let state = await SyncroEntities[entity].initState({
-					supabase: Syncro.supabase,
-					fsCollection, fsId,
-					entity, id, relation,
+				let state = await SyncroEntities[entityKey].initState({
+					supabasey: Syncro.supabasey,
+					id, relation,
 				});
 
 				await this.keyedAssign(state);
 			})
 			.then(()=> { // Create the reactive
 				let reactive = this.getReactive(this.proxy());
+				// Assuming this.value should hold the reactive proxy
+				// If this.value is inherited and has a specific type, this might need adjustment
 				this.value = reactive.doc;
 			})
 			.then(()=> this)
@@ -140,38 +158,46 @@ export default class SyncroKeyed extends Syncro {
 	*
 	* @returns {Proxy} A proxy of all combined members
 	*/
-	proxy() {
+	proxy(): Record<string | symbol, any> { // Return type can be more specific if needed
 		return new Proxy(this, {
 			// Return the full list of keys
-			ownKeys(target) {
-				return target.members.flatMap(m => Object.keys(m.value));
+			ownKeys(target: SyncroKeyed): ArrayLike<string | symbol> {
+				return target.members.flatMap(m => Object.keys(m.value || {}));
 			},
 
 			// Return if we have a lookup key
-			has(target, prop) {
-				return target.members.some(m => !! m.value[prop]);
+			has(target: SyncroKeyed, prop: string | symbol): boolean {
+				// Ensure m.value exists before checking property
+				return target.members.some(m => m.value && prop in m.value);
 			},
 
 			// Scope through members until we get a hit on the key
-			get(target, prop) {
-				let targetMember = target.members.find(m => prop in m.value);
-				return targetMember ? targetMember[prop] : undefined;
+			get(target: SyncroKeyed, prop: string | symbol): any {
+				let targetMember = target.members.find(m => m.value && prop in m.value);
+				// Access value via targetMember.value if found
+				return targetMember ? targetMember.value[prop] : undefined;
 			},
 
 			// Set the member key if one already exists, otherwise overflow onto the next member
-			set(target, prop, value) {
-				let targetMember = target.members.find(m => prop in m.value);
-				if (targetMember) {
-					targetMember[prop] = value;
+			set(target: SyncroKeyed, prop: string | symbol, value: any): boolean {
+				let targetMember = target.members.find(m => m.value && prop in m.value);
+				if (targetMember && targetMember.value) {
+					targetMember.value[prop] = value;
 				} else {
-					target.keyedSet(prop, value);
+					// Assuming keyedSet handles adding the value appropriately
+					target.keyedSet(prop as string, value); // Cast prop to string if keyedSet expects string
 				}
+				return true; // Proxy set must return boolean
 			},
 
 			// Remove a key
-			deleteProperty(target, prop) {
-				let targetMember = target.members.find(m => prop in m);
-				if (targetMember) targetMember.value[prop];
+			deleteProperty(target: SyncroKeyed, prop: string | symbol): boolean {
+				let targetMember = target.members.find(m => m.value && prop in m.value);
+				if (targetMember && targetMember.value) {
+					delete targetMember.value[prop];
+					return true; // Indicate success
+				}
+				return false; // Indicate key not found or failure
 			},
 		});
 	}
@@ -185,21 +211,22 @@ export default class SyncroKeyed extends Syncro {
 	*
 	* @returns {Promise} A promise which resolves when the operation has completed
 	*/
-	async flush(options) {
-		let settings = {
+	async flush(options?: FlushOptions): Promise<void> { // Match base class signature
+		let settings: FlushOptions = {
 			destroy: false,
 			...options,
 		};
 
 		await Promise.all(
 			this.members.map(member =>
-				member.flush({
+				member.flush({ // Assuming member.flush returns Promise<void> now
 					destroy: settings.destroy,
 				})
 			)
 		);
 
 		if (settings.destroy) await this.destroy();
+		return; // Return void to match signature
 	}
 
 
@@ -212,19 +239,28 @@ export default class SyncroKeyed extends Syncro {
 	*
 	* @returns {Promise<*>} A promise which resolves when the operation has completed with the set value
 	*/
-	async keyedSet(key, value) {
-		let candidateMember = this.members.find(m => Object.keys(m.value).length < this.config.maxKeys);
-		if (candidateMember) {
-			return candidateMember.value[key] = value;
+	async keyedSet(key: string, value: any): Promise<any> {
+		let candidateMember = this.members.find(m => m.value && Object.keys(m.value).length < this.keyedConfig.maxKeys);
+		if (candidateMember?.value) {
+			candidateMember.value[key] = value;
+			return value;
 		} else { // No candidate - need to expand then set
 			// Extend members
-			await this.keyedMembersExpand();
+			await this.keyedMembersExpand(); // Call without index to append
+
+			// Get the newly added member
+			let newMember = this.members.at(-1);
+			if (!newMember || !newMember.value) {
+				throw new Error('Failed to expand members or new member has no value object');
+			}
 
-			// Sanity check
-			let candidateMember = this.members.at(-1);
-			if (Object.keys(candidateMember).length >= this.config.maxKeys) throw new Error(`Need to append key "${key}" but newly added member doesnt have enough room. Member offset #${this.members.length-1} has size of ${Object.keys(candidateMember).length}`);
+			// Sanity check (check the new member's value)
+			if (Object.keys(newMember.value).length >= this.keyedConfig.maxKeys) {
+				throw new Error(`Need to append key "${key}" but newly added member (offset #${this.members.length-1}) has size of ${Object.keys(newMember.value).length}, exceeding maxKeys ${this.keyedConfig.maxKeys}`);
+			}
 
-			return candidateMember.value[key] = value;
+			newMember.value[key] = value;
+			return value;
 		}
 	}
 
@@ -236,9 +272,10 @@ export default class SyncroKeyed extends Syncro {
 	*
 	* @param {Object} state The value to merge
 	*/
-	async keyedAssign(state) {
+	async keyedAssign(state: Record<string, any>): Promise<void> {
 		// Can we assume we have a blank state - this speeds up existing key checks significantly
-		let isBlank = this.members.length == 1 && Object.keys(this.members[0].value).length == 0;
+		// Ensure members[0] and its value exist
+		let isBlank = this.members.length === 1 && this.members[0]?.value && Object.keys(this.members[0].value).length === 0;
 
 		if (isBlank) {
 			let chunks = chunk(Object.entries(state), this.keyedConfig.maxKeys)
@@ -251,16 +288,22 @@ export default class SyncroKeyed extends Syncro {
 					// Create chunk document if its missing
 					if (!this.members[chunkIndex]) await this.keyedMembersExpand(chunkIndex);
 
-					// Populate its state
-					await this.members[chunkIndex].setFirestoreState(chunk, {method: 'set'});
+					// Ensure the member exists and has setFirestoreState method
+                    const member = this.members[chunkIndex];
+                    if (member && typeof (member as any).setFirestoreState === 'function') {
+					    // Populate its state - Cast to any temporarily if setFirestoreState is not public/recognized
+					    await (member as any).setFirestoreState(chunk, {method: 'set'});
+                    } else {
+                        console.warn(`Member at index ${chunkIndex} is missing or does not have setFirestoreState`);
+                    }
 				})
 			);
 
 		} else { // Non-blank - call keyedSet() on each key of state, merging slowly
-			await Array.fromAsync( // In a promise-series chain call keyedSet for each item
-				Object.entries(state),
-				([key, val]) => this.keyedSet(key, val),
-			);
+			// Replace Array.fromAsync with a standard loop
+            for (const [key, val] of Object.entries(state)) {
+                await this.keyedSet(key, val);
+            }
 		}
 	}
 
@@ -271,12 +314,21 @@ export default class SyncroKeyed extends Syncro {
 	* @param {Number} [index] The index to use when expanding, if omitted the next index offset is used
 	* @returns {Promise} A promise which resolves when the operation has completed
 	*/
-	async keyedMembersExpand(index) {
-		index ??= this.members.length;
-		if (this.members[index]) throw new Error(`keyedMembersExpand(${index}) but index already exists`);; // Member already exists
+	async keyedMembersExpand(index?: number): Promise<void> {
+		index = index ?? this.members.length; // Use provided index or next available slot
+		if (this.members[index]) {
+            // If member already exists (e.g., during initial seek), just ensure it's mounted.
+            // If it was called intentionally with an existing index, maybe log a warning or skip.
+            this.debug(`keyedMembersExpand called for existing index ${index}, ensuring mounted.`);
+            if (!this.members[index].value) { // If it exists but isn't mounted somehow
+                 await this.members[index].mount({ initialState: {} });
+            }
+            return; // Exit if member already exists
+        }
 
 		let syncroPath = this.keyedPath.getKey(this.path, index);
-		let {fsCollection, fsId} = Syncro.pathSplit(syncroPath);
+		// Pass empty options object {} or specify allowAsterisk: false if needed
+		let {fsCollection, fsId} = Syncro.pathSplit(syncroPath, {}) as PathSplitResult;
 		this.debug('Expand SyncroKeyed size to index=', index);
 
 		// Create a new Syncro member, inheriteing some details from this parent item
@@ -290,7 +342,12 @@ export default class SyncroKeyed extends Syncro {
 			initialState: {}, // Force intital state to empty object so we don't get stuck in a loop
 		});
 
-		this.members.push(syncro);
+		// Insert at the correct index if specified, otherwise push
+        if (index < this.members.length) {
+            this.members.splice(index, 0, syncro);
+        } else {
+		    this.members.push(syncro);
+        }
 	}
 
 }