@verdant-web/store 3.6.3 → 3.6.4

package/dist/esm/entities/types.d.ts

@@ -42,6 +42,7 @@ export type DeepPartial<T> = T extends object ? {
 } : T;
 export interface ObjectEntity<Init, Value extends BaseEntityValue, Snapshot = DataFromInit<Init>> extends BaseEntity<Init, Value, Snapshot> {
     keys(): string[];
+    readonly size: number;
     entries(): [string, Exclude<Value[keyof Value], undefined>][];
     values(): Exclude<Value[keyof Value], undefined>[];
     set<Key extends keyof Init>(key: Key, value: Init[Key]): void;
@@ -69,6 +70,16 @@ export interface ObjectEntity<Init, Value extends BaseEntityValue, Snapshot = Da
          */
         merge?: boolean;
     }): void;
+    /**
+     * Deletes the entity from either its parent (if it's a nested value)
+     * or the database itself. WARNING: this method is tricky. It will
+     * throw an error on nested fields which are not deletable in the
+     * schema. Deleting any entity and then attempting to access its
+     * data will also result in an error.
+     *
+     * Prefer using client.<collection>.delete(id) instead.
+     */
+    deleteSelf(): void;
     readonly isList: false;
 }
 export interface ListEntity<Init, Value extends BaseEntityValue, Snapshot = DataFromInit<Init>> extends Iterable<ListItemValue<Value>>, BaseEntity<Init, Value, Snapshot> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verdant-web/store",
-  "version": "3.6.3",
+  "version": "3.6.4",
   "access": "public",
   "type": "module",
   "exports": {

package/src/__tests__/documents.test.ts

@@ -463,6 +463,20 @@ describe('storage documents', () => {
 		expect(item1.get('tags').deepUpdatedAt).not.toEqual(time.getTime());
 	});
 
+	it('should expose namespace', async () => {
+		const storage = await createTestStorage();
+
+		const item1 = await storage.todos.put({
+			content: 'item 1',
+			done: false,
+			tags: [],
+			category: 'general',
+			attachments: [],
+		});
+
+		expect(item1.namespace).toBe('test');
+	});
+
 	it('should allow creating a new document from another document snapshot', async () => {
 		const storage = await createTestStorage();
 		const item1 = await storage.todos.put({
@@ -592,4 +606,18 @@ describe('storage documents', () => {
 		expect(fooArray.get(0)).toEqual('bar');
 		expect(arrayMap.get('foo').get(0)).toEqual('bar');
 	});
+
+	it('should not fire change event on delete', async () => {
+		const storage = await createTestStorage();
+		const created = await storage.weirds.put({});
+		const weird = await storage.weirds.get(created.get('id')).resolved!;
+
+		weird.subscribe('change', () => {
+			// never get a change with deleted data
+			expect(weird.deleted).toBe(false);
+		});
+
+		await storage.weirds.delete(weird.get('id'));
+		expect(true).toBe(true);
+	});
 });

package/src/__tests__/mutations.test.ts

@@ -54,4 +54,57 @@ describe('mutations', () => {
 		expect(itemAExists).toBeNull();
 		expect(itemBExists === itemB).toBe(true);
 	});
+
+	describe('on entities', () => {
+		it('should allow them to delete themselves (root level)', async () => {
+			const client = await createTestStorage();
+
+			const itemA = await client.todos.put({
+				id: '1',
+				content: 'itemA',
+				category: 'test',
+			});
+
+			await itemA.deleteSelf();
+
+			const itemAExists = await client.todos.get('1').resolved;
+
+			expect(itemAExists).toBeNull();
+		});
+
+		it('should allow them to delete themselves (nested array)', async () => {
+			const client = await createTestStorage();
+
+			const itemA = await client.todos.put({
+				id: '1',
+				content: 'itemA',
+				category: 'test',
+				attachments: [
+					{
+						name: 'foo',
+					},
+				],
+			});
+
+			itemA.get('attachments').get(0).deleteSelf();
+
+			expect(itemA.get('attachments').length).toBe(0);
+		});
+
+		it('should allow them to delete themselves (nested map)', async () => {
+			const client = await createTestStorage();
+
+			const weird = await client.weirds.put({
+				objectMap: {
+					foo: {
+						content: 'bar',
+					},
+				},
+			});
+
+			weird.get('objectMap').get('foo').deleteSelf();
+
+			expect(weird.get('objectMap').size).toBe(0);
+		});
+	});
 });

package/src/entities/Entity.test.ts

@@ -79,6 +79,7 @@ describe('Entity', () => {
 			} as any as FileManager,
 			patchCreator,
 			readonlyKeys: ['id'],
+			deleteSelf: vi.fn(),
 		});
 
 		function initialize(data: any) {

package/src/entities/Entity.ts

@@ -58,6 +58,7 @@ export interface EntityInit {
 	fieldPath?: (string | number)[];
 	patchCreator: PatchCreator;
 	events: EntityStoreEvents;
+	deleteSelf: () => void;
 }
 
 export class Entity<
@@ -94,6 +95,9 @@ export class Entity<
 	// only used for root entities to track delete/restore state.
 	private wasDeletedLastChange = false;
 	private cachedView: any | undefined = undefined;
+	// provided from external creators, this is a method to delete
+	// this entity.
+	private _deleteSelf: () => void;
 
 	constructor({
 		oid,
@@ -106,6 +110,7 @@ export class Entity<
 		files,
 		patchCreator,
 		events,
+		deleteSelf,
 	}: EntityInit) {
 		super();
 
@@ -125,6 +130,7 @@ export class Entity<
 		this.metadataFamily = metadataFamily;
 		this.events = events;
 		this.parent = parent;
+		this._deleteSelf = deleteSelf;
 
 		// TODO: should any but the root entity be listening to these?
 		if (!this.parent) {
@@ -366,6 +372,15 @@ export class Entity<
 		return this.viewData.fromOlderVersion;
 	}
 
+	/**
+	 * Returns the storage namespace this entity came from. For example, if you
+	 * have multiple stores initialized from the same schema, you can use this
+	 * to figure out where an isolated entity was created / stored.
+	 */
+	get namespace() {
+		return this.ctx.namespace;
+	}
+
 	/**
 	 * Pruning - when entities have invalid children, we 'prune' that
 	 * data up to the nearest prunable point - a nullable field,
@@ -465,25 +480,10 @@ export class Entity<
 			// reset cached view
 			this._viewData = undefined;
 			this.cachedView = undefined;
-			// chain deepChanges to parents
-			this.deepChange(this, ev);
-			// emit the change, it's for us
-			this.ctx.log('Emitting change event', this.oid);
-			this.emit('change', { isLocal: ev.isLocal });
-			// for root entities, we need to go ahead and decide if we're
-			// deleted or not - so queries can exclude us if we are.
 			if (!this.parent) {
-				// newly deleted - emit event
-				if (this.deleted && !this.wasDeletedLastChange) {
-					this.ctx.log('debug', 'Entity deleted', this.oid);
-					this.emit('delete', { isLocal: ev.isLocal });
-					this.wasDeletedLastChange = true;
-				} else if (!this.deleted && this.wasDeletedLastChange) {
-					this.ctx.log('debug', 'Entity restored', this.oid);
-					// newly restored - emit event
-					this.emit('restore', { isLocal: ev.isLocal });
-					this.wasDeletedLastChange = false;
-				}
+				this.changeRoot(ev);
+			} else {
+				this.changeNested(ev);
 			}
 		} else {
 			// forward it to the correct family member. if none exists
@@ -494,6 +494,36 @@ export class Entity<
 			}
 		}
 	};
+	private changeRoot = (ev: EntityChange) => {
+		// for root entities, we need to determine if we're deleted or not
+		// before firing any events
+		if (this.deleted) {
+			if (!this.wasDeletedLastChange) {
+				this.ctx.log('debug', 'Entity deleted', this.oid);
+				this.emit('delete', { isLocal: ev.isLocal });
+				this.wasDeletedLastChange = true;
+			}
+			// already deleted, do nothing.
+		} else {
+			if (this.wasDeletedLastChange) {
+				this.ctx.log('debug', 'Entity restored', this.oid);
+				this.emit('restore', { isLocal: ev.isLocal });
+				this.wasDeletedLastChange = false;
+			}
+			// emit deepchange, too
+			this.deepChange(this, ev);
+			// emit the change, it's for us
+			this.ctx.log('Emitting change event', this.oid);
+			this.emit('change', { isLocal: ev.isLocal });
+		}
+	};
+	private changeNested = (ev: EntityChange) => {
+		// chain deepChanges to parents
+		this.deepChange(this, ev);
+		// emit the change, it's for us
+		this.ctx.log('Emitting change event', this.oid);
+		this.emit('change', { isLocal: ev.isLocal });
+	};
 	protected deepChange = (target: Entity, ev: EntityChange) => {
 		// reset cached deep updated at timestamp; either this
 		// entity or children have changed
@@ -530,6 +560,7 @@ export class Entity<
 			fieldPath: [...this.fieldPath, key],
 			patchCreator: this.patchCreator,
 			events: this.events,
+			deleteSelf: this.delete.bind(this, key),
 		});
 	};
 
@@ -781,6 +812,13 @@ export class Entity<
 		return Object.values(this.view);
 	};
 
+	get size() {
+		if (this.isList) {
+			return this.length;
+		}
+		return this.keys().length;
+	}
+
 	update = (
 		data: any,
 		{
@@ -976,6 +1014,21 @@ export class Entity<
 
 	includes = this.has;
 
+	/**
+	 * Deletes this entity. WARNING: this can be tricky to
+	 * use correctly. You must not reference this entity
+	 * instance in any way after the deletion happens, or
+	 * you will get an error!
+	 *
+	 * It's a little easier to delete using client.delete
+	 * if you can manage it with your app's code. For example,
+	 * in React, use hooks.useClient() to get the client and
+	 * call delete from there.
+	 */
+	deleteSelf = () => {
+		return this._deleteSelf();
+	};
+
 	// TODO: make these escape hatches unnecessary
 	__getViewData__ = (oid: ObjectIdentifier, type: 'confirmed' | 'pending') => {
 		return this.metadataFamily.get(oid).computeView(type === 'confirmed');

package/src/entities/EntityStore.ts

@@ -451,6 +451,7 @@ export class EntityStore extends Disposable {
 			metadataFamily: metadataFamily,
 			patchCreator: this.meta.patchCreator,
 			events: this.events,
+			deleteSelf: this.delete.bind(this, oid),
 		});
 	};
 

package/src/entities/types.ts

@@ -84,6 +84,7 @@ export interface ObjectEntity<
 	Snapshot = DataFromInit<Init>,
 > extends BaseEntity<Init, Value, Snapshot> {
 	keys(): string[];
+	readonly size: number;
 	entries(): [string, Exclude<Value[keyof Value], undefined>][];
 	values(): Exclude<Value[keyof Value], undefined>[];
 	set<Key extends keyof Init>(key: Key, value: Init[Key]): void;
@@ -114,6 +115,16 @@ export interface ObjectEntity<
 			merge?: boolean;
 		},
 	): void;
+	/**
+	 * Deletes the entity from either its parent (if it's a nested value)
+	 * or the database itself. WARNING: this method is tricky. It will
+	 * throw an error on nested fields which are not deletable in the
+	 * schema. Deleting any entity and then attempting to access its
+	 * data will also result in an error.
+	 *
+	 * Prefer using client.<collection>.delete(id) instead.
+	 */
+	deleteSelf(): void;
 	readonly isList: false;
 }