@harperfast/harper-pro 5.0.30 → 5.1.0-beta.2

package/core/resources/RecordEncoder.ts

@@ -6,8 +6,7 @@
  */
 
 import { Encoder } from 'msgpackr';
-import { get as envGet } from '../utility/environment/environmentManager.js';
-import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
+import { createStructon } from 'structon';
 import {
 	HAS_PREVIOUS_RESIDENCY_ID,
 	HAS_CURRENT_RESIDENCY_ID,
@@ -17,7 +16,7 @@ import {
 	ACTION_32_BIT,
 	HAS_ADDITIONAL_AUDIT_REFS as HAS_ADDITIONAL_AUDIT_REFS_AUDIT,
 } from './auditStore.ts';
-import * as harperLogger from '../utility/logging/harper_logger.js';
+import * as harperLogger from '../utility/logging/harper_logger.ts';
 import './blob.ts';
 import {
 	blobsWereEncoded,
@@ -31,6 +30,10 @@ import { getThisNodeId } from './nodeIdMapping.ts';
 import { recordAction } from './analytics/write.ts';
 import { RocksDatabase } from '@harperfast/rocksdb-js';
 import { when } from '../utility/when.ts';
+import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
+import * as envMngr from '../utility/environment/environmentManager.js';
+
+const StructonEncoder = createStructon(Encoder) as typeof Encoder;
 export type Entry = {
 	key: any;
 	value: any;
@@ -42,6 +45,7 @@ export type Entry = {
 	residencyId: number;
 	size: number;
 	deref?: () => any;
+	[METADATA]?: any;
 	additionalAuditRefs?: Array<{ version: number; nodeId: number }>;
 };
 
@@ -82,7 +86,11 @@ let timestampNextEncoding = 0,
 	additionalAuditRefsNextEncoding: Array<{ version: number; nodeId: number }> | undefined;
 // tracking metadata with a singleton works better than trying to alter response of getEntry/get and coordinating that across caching layers
 export let lastMetadata: Entry | null = null;
-export class RecordEncoder extends Encoder {
+export class RecordEncoder extends StructonEncoder {
+	rootStore: any;
+	declare saveStructures: any;
+	declare getStructures: any;
+	declare _writeStruct: any;
 	structureUpdate?: any;
 	isRocksDB: boolean;
 	name: string;
@@ -92,16 +100,6 @@ export class RecordEncoder extends Encoder {
 		// long-lived primary store, so a wide/sparse schema (whose records vary by per-field value
 		// width) can grow it unbounded and exhaust memory. Caller-overridable; default caps it.
 		options.maxOwnStructures ??= 256;
-		// When random-access fields are disabled (storage.randomAccessFields=false), write records as
-		// classic shared structures instead of typed random-access structures. randomAccessStructure stays
-		// on so reads still decode either form — existing typed-struct data remains readable; only new
-		// writes change. lmdb-js does not forward non-whitelisted encoder options, so the flag is derived
-		// from the global config here rather than passed through the store options. Read at construction
-		// (DBI open, a cold path) so env/CLI config overrides are applied; an explicit option still wins
-		// (e.g. rocksdb-js's option spread, or tests).
-		if (options.readOnlyStructures === undefined && envGet(CONFIG_PARAMS.STORAGE_RANDOMACCESSFIELDS) === false) {
-			options.readOnlyStructures = true;
-		}
 		/**
 		 * The base class for records that provides the read-only methods for accessing
 		 * metadata and will be assigned computed property getters. On its own, these instances
@@ -119,6 +117,16 @@ export class RecordEncoder extends Encoder {
 
 		options.structPrototype = RecordObject.prototype;
 		super(options);
+		// structon (the StructonEncoder base) always installs the struct write hook. For DBIs
+		// that don't opt into struct mode (non-primary, e.g. __dbis__), force it to bail (return
+		// 0) so objects are written in plain msgpackr records mode — decodable by readers without
+		// struct support (msgpackr v1 / Harper v4 downgrade). We make it bail rather than clear
+		// it so msgpackr keeps the struct-safe integer boundary: top-level integers 0x20-0x3f are
+		// written as uint8 rather than bare fixints, which the retained struct READ hook would
+		// otherwise misread as struct headers (e.g. a scalar NEXT_TABLE_ID >= 32 in __dbis__).
+		// The read hook stays intact so records already written in struct mode by a prior v5 still
+		// decode.
+		if (!options.randomAccessStructure) this._writeStruct = () => 0;
 		const superEncode = this.encode;
 		this.encode = function (record, options?) {
 			// this handles our custom metadata encoding, prefixing the record with metadata, including the local
@@ -226,9 +234,9 @@ export class RecordEncoder extends Encoder {
 				// We must report a non-commit as `false` (not the buggy `undefined`, which msgpackr
 				// reads as success and then writes a record referencing a structure that was never
 				// saved → later "Record id is not defined" on decode). Returning `false` makes msgpackr
-				// re-pack; paired with msgpackr 1.11.14's structures-rebuild-on-save-failure fix, the
-				// re-pack reloads the durable structures, rebuilds the transition trie, re-mints, and
-				// re-saves — so the record always references a persisted structure.
+				// re-pack; paired with the msgpackr fix that marks structures uninitialized on
+				// save-failure, the re-pack reloads the durable structures, rebuilds the transition
+				// trie, re-mints, and re-saves — so the record always references a persisted structure.
 				const committed = this.rootStore.transactionSync(
 					(txn) => {
 						const sharedStructuresKey = [Symbol.for('structures'), this.name];
@@ -283,7 +291,7 @@ export class RecordEncoder extends Encoder {
 			// timestamped record (8 bytes stripped → corrupt). Callers that pass a value known to have no
 			// prefix (e.g. the audit store's getValue) set options.noMetadata to skip the heuristic. Typed
 			// structs start at 0x20-0x3f and never hit this, which is why it only surfaces with classic
-			// structures (random-access fields off).
+			// structures (typed structures off).
 			if (!options?.noMetadata && ((this.isRocksDB && nextByte === 66) || (nextByte < 32 && end > 2))) {
 				// record with metadata
 				// this means that the record starts with a local timestamp (that was assigned by lmdb-js).
@@ -370,7 +378,7 @@ export class RecordEncoder extends Encoder {
 					additionalAuditRefs,
 					size: end - start,
 					value,
-				};
+				} as any;
 				if (this.isRocksDB) return lastMetadata;
 				return value;
 			} // else a normal entry
@@ -381,21 +389,6 @@ export class RecordEncoder extends Encoder {
 		}
 	}
 }
-
-/**
- * Encoder for custom-index object stores (e.g. HNSW vector graphs). These hold fixed-shape internal
- * nodes — numeric-keyed per-level connection arrays and quantized bins — that depend on random-access
- * struct encoding and are mutated in place during graph maintenance. Keep them writing typed structs
- * even when storage.randomAccessFields disables structs for user tables: their node shapes are
- * controlled, so the wide/heterogeneous OOM risk that motivates opt-out doesn't apply, and classic
- * (frozen) decoding would break the in-place graph mutation.
- */
-export class IndexRecordEncoder extends RecordEncoder {
-	constructor(options) {
-		options.readOnlyStructures = false;
-		super(options);
-	}
-}
 function getTimestamp() {
 	TIMESTAMP_HOLDER[0] = TIMESTAMP_HOLDER[0] ^ 0x40; // restore the first byte, we xor to differentiate the first byte from structures
 	return TIMESTAMP_VIEW.getFloat64(0);
@@ -536,6 +529,7 @@ export function handleLocalTimeForGets(store, rootStore) {
 				use.call(this);
 			};
 			Txn.prototype.done = function () {
+				if (this.isDone) return;
 				done.call(this);
 				this.openTimer = 0; // reset so idle pool time doesn't accumulate toward the stale-open threshold
 				if (this.isDone) {
@@ -554,16 +548,18 @@ export function handleLocalTimeForGets(store, rootStore) {
 	return store;
 }
 const trackedTxns: WeakRef<any>[] = [];
-setInterval(() => {
+const configValue = envMngr.get(CONFIG_PARAMS.STORAGE_MAX_READ_TRANSACTION_OPEN_TIME) ?? 300000;
+let READ_TXN_TIMEOUT_TICKS = Math.round(configValue / 15000);
+export function checkReadTxnTimeouts() {
 	for (let i = 0; i < trackedTxns.length; i++) {
 		const txn = trackedTxns[i].deref();
 		if (!txn || txn.isDone || txn.isCommitted) trackedTxns.splice(i--, 1);
 		else if (txn.notCurrent) {
 			if (txn.openTimer) {
 				if (txn.openTimer > 3) {
-					if (txn.openTimer > 60) {
+					if (txn.openTimer > READ_TXN_TIMEOUT_TICKS) {
 						harperLogger.error(
-							'Read transaction detected that has been open too long (over 15 minutes), ending transaction',
+							`Read transaction detected that has been open too long (over ${Math.round(READ_TXN_TIMEOUT_TICKS * 15)} seconds), ending transaction`,
 							txn
 						);
 						trackedTxns.splice(i--, 1);
@@ -584,7 +580,12 @@ setInterval(() => {
 			} else txn.openTimer = 1;
 		}
 	}
-}, 15000).unref();
+}
+setInterval(checkReadTxnTimeouts, 15000).unref();
+export function setReadTxnExpiration(ms: number) {
+	READ_TXN_TIMEOUT_TICKS = Math.round(ms / 15000);
+	return trackedTxns;
+}
 export function setNextEncoding(timestamp: number, metadata: number, expiresAt = -1, nodeId = -1, residencyId = 0) {
 	timestampNextEncoding = timestamp;
 	metadataInNextEncoding = metadata;
@@ -632,6 +633,7 @@ export function recordUpdater(store, tableId, auditStore) {
 			version: number;
 			instructedWrite?: boolean;
 			ifVersion?: number;
+			transaction?: any;
 		} = {
 			version: newVersion,
 			instructedWrite: timestampNextEncoding > 0,
@@ -647,7 +649,7 @@ export function recordUpdater(store, tableId, auditStore) {
 				metadataInNextEncoding |= HAS_RESIDENCY_ID;
 				extendedType |= HAS_CURRENT_RESIDENCY_ID;
 			} else residencyIdAtNextEncoding = 0;
-			const nodeId = options?.nodeId;
+			const nodeId = options?.nodeId ?? (audit ? getThisNodeId(auditStore) : undefined);
 			if (nodeId >= 0) {
 				nodeIdAtNextEncoding = nodeId;
 				metadataInNextEncoding |= HAS_NODE_ID;

package/core/resources/RequestTarget.ts

@@ -15,6 +15,8 @@ export class RequestTarget extends URLSearchParams {
 	/** Request best effort and returning synchronously */
 	declare syncAllowed?: boolean;
 
+	declare sync?: boolean;
+
 	/** Indicates that this is a request to query for collection of records */
 	isCollection?: boolean;
 	// these are query parameters

package/core/resources/Resource.ts

@@ -1,5 +1,5 @@
 import type { User } from '../security/user.ts';
-import type { RecordObject } from './RecordEncoder.js';
+import type { RecordObject } from './RecordEncoder.ts';
 import {
 	ResourceInterface,
 	SubscriptionRequest,
@@ -13,11 +13,12 @@ import { randomUUID } from 'crypto';
 import { DatabaseTransaction, type Transaction } from './DatabaseTransaction.ts';
 import { IterableEventQueue } from './IterableEventQueue.ts';
 import { _assignPackageExport } from '../globals.js';
-import { ClientError, AccessViolation } from '../utility/errors/hdbError.js';
+import { ClientError, AccessViolation } from '../utility/errors/hdbError.ts';
 import { transaction, contextStorage } from './transaction.ts';
 import { parseQuery } from './search.ts';
 import { RequestTarget } from './RequestTarget.ts';
 import { when, promiseNormalize } from '../utility/when.ts';
+import type { JsonSchemaFragment } from './jsonSchemaTypes.ts';
 
 const EXTENSION_TYPES = {
 	json: 'application/json',
@@ -45,17 +46,38 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	static transactions: Transaction[] & { timestamp: number };
 	static directURLMapping = false;
 	static loadAsInstance: boolean;
+	static description?: string;
+	static properties?: { [name: string]: JsonSchemaFragment };
+	static outputSchemas?: { [verb: string]: JsonSchemaFragment };
+	static mcp?: { annotations?: { [verb: string]: { [key: string]: unknown } } };
+	static hidden?: boolean;
 	constructor(identifier: Id, source: any) {
 		this.#id = identifier;
 		const context = source?.getContext ? (source.getContext() ?? null) : undefined;
 		this.#context = context !== undefined ? context : source || null;
 	}
 
+	doesExist(): boolean {
+		return true; // Subclasses should override if needed
+	}
+
+	wasLoadedFromSource(): boolean | void {
+		// Subclasses should override if needed
+	}
+
+	addTo(_property: keyof Record, _value: Record[keyof Record]): void {
+		throw new Error('Not implemented');
+	}
+
+	subtractFrom(_property: keyof Record, _value: Record[keyof Record]): void {
+		throw new Error('Not implemented');
+	}
+
 	/**
 	 * The get methods are for directly getting a resource, and called for HTTP GET requests.
 	 */
 	static get = transactional(
-		function (resource: Resource, query: RequestTarget, _request: Context, _data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, _data: any) {
 			const result = resource.get?.(query);
 			// for the new API we always apply select in the instance method
 			if (!resource.constructor.loadAsInstance) return result;
@@ -89,7 +111,7 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	 * Store the provided record by the provided id. If no id is provided, it is auto-generated.
 	 */
 	static put = transactional(
-		function (resource: Resource, query: RequestTarget, request: Context, data: any) {
+		function (resource: any, query: RequestTarget, request: Context, data: any) {
 			if (Array.isArray(data) && resource.#isCollection && resource.constructor.loadAsInstance !== false) {
 				const results = [];
 				for (const element of data) {
@@ -115,7 +137,7 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	);
 
 	static patch = transactional(
-		function (resource: Resource, query: RequestTarget, _request: Context, data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, data: any) {
 			// TODO: Allow array like put?
 			return resource.patch
 				? resource.constructor.loadAsInstance === false
@@ -127,7 +149,7 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	);
 
 	static delete = transactional(
-		function (resource: Resource, query: RequestTarget, _request: Context, _data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, _data: any) {
 			return resource.delete ? resource.delete(query) : missingMethod(resource, 'delete');
 		},
 		{ hasContent: false, type: 'delete', method: 'delete' }
@@ -150,7 +172,7 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	static create(idPrefix: Id, record: any, context: Context): Promise<Id>;
 	static create(record: any, context: Context): Promise<Id>;
 	static create(idPrefix: any, record: any, context?: Context): Promise<Id> {
-		let id: Id;
+		let id: any;
 		if (this.loadAsInstance === false) {
 			if (typeof idPrefix === 'object' && idPrefix && !context) {
 				// two argument form (record, context), shift the arguments
@@ -160,44 +182,45 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 				id.isCollection = true;
 			} else id = idPrefix;
 		} else {
-			if (idPrefix == null) id = record?.[this.primaryKey] ?? this.getNewId();
+			const primaryKey = (this as any).primaryKey;
+			if (idPrefix == null) id = record?.[primaryKey] ?? this.getNewId();
 			else if (Array.isArray(idPrefix) && typeof idPrefix[0] !== 'object')
-				id = record?.[this.primaryKey] ?? [...idPrefix, this.getNewId()];
-			else if (typeof idPrefix !== 'object') id = record?.[this.primaryKey] ?? [idPrefix, this.getNewId()];
+				id = record?.[primaryKey] ?? [...idPrefix, this.getNewId()];
+			else if (typeof idPrefix !== 'object') id = record?.[primaryKey] ?? [idPrefix, this.getNewId()];
 			else {
 				// two argument form, shift the arguments
-				id = idPrefix?.[this.primaryKey] ?? this.getNewId();
+				id = idPrefix?.[primaryKey] ?? this.getNewId();
 				context = record || {};
 				record = idPrefix;
 			}
 		}
 		if (context) {
-			if (context.getContext) context = context.getContext();
+			if ((context as any).getContext) context = (context as any).getContext();
 		} else {
 			// try to get the context from the async context if possible
 			context = contextStorage.getStore() ?? {};
 		}
 		return transaction(context, async () => {
-			context.transaction.startedFrom ??= {
+			(context as any).transaction.startedFrom ??= {
 				resourceName: this.name,
 				method: 'create',
 			};
-			const resource = new this(id, context);
+			const resource = new (this as any)(id, context);
 			const results = resource.create ? await resource.create(id, record) : missingMethod(resource, 'create');
-			context.newLocation = id ?? results?.[this.primaryKey];
-			context.createdResource = true;
+			(context as any).newLocation = id ?? results?.[(this as any).primaryKey];
+			(context as any).createdResource = true;
 			return this.loadAsInstance === false ? results : resource;
 		});
 	}
 	static invalidate = transactional(
-		function (resource: Resource, query: RequestTarget, _request: Context, _data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, _data: any) {
 			return resource.invalidate ? resource.invalidate(query) : missingMethod(resource, 'invalidate');
 		},
 		{ hasContent: false, type: 'update', method: 'invalidate' }
 	);
 
 	static post = transactional(
-		function (resource: Resource, query: RequestTarget, _request: Context, data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, data: any) {
 			if (resource.#id != null) resource.update?.(); // save any changes made during post
 			return resource.constructor.loadAsInstance === false ? resource.post(query, data) : resource.post(data, query);
 		},
@@ -205,14 +228,14 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	);
 
 	static update = transactional(
-		function (resource: Resource, query: RequestTarget, _request: Context, data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, data: any) {
 			return resource.update(query, data);
 		},
 		{ type: 'update', method: 'update' }
 	);
 
 	static connect = transactional(
-		function (resource: Resource, query: RequestTarget, _request: Context, data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, data: any) {
 			return resource.connect
 				? resource.constructor.loadAsInstance === false
 					? resource.connect(query, data)
@@ -223,14 +246,14 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	);
 
 	static subscribe = transactional(
-		function (resource: Resource, query: RequestTarget, _request: Context, _data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, _data: any) {
 			return resource.subscribe ? resource.subscribe(query) : missingMethod(resource, 'subscribe');
 		},
 		{ type: 'read', method: 'subscribe', syncAllowed: true }
 	);
 
 	static publish = transactional(
-		function (resource: Resource, query: Map, _request: Context, data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, data: any) {
 			if (resource.#id != null) resource.update?.(); // save any changes made during publish
 			return resource.publish
 				? resource.constructor.loadAsInstance === false
@@ -242,9 +265,9 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	);
 
 	static search = transactional(
-		function (resource: Resource, query: Query, request: Context) {
+		function (resource: any, query: Query, request: Context) {
 			const result = resource.search ? resource.search(query) : missingMethod(resource, 'search');
-			const select = request.select;
+			const select = (request as any).select;
 			if (select && request.hasOwnProperty('select') && result != null && !result.selectApplied) {
 				const transform = transformForSelect(select, resource.constructor);
 				return result.map(transform);
@@ -255,7 +278,7 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	);
 
 	static query = transactional(
-		function (resource: Resource, query: Map, _request: Context, data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, data: any) {
 			return resource.search
 				? resource.constructor.loadAsInstance === false
 					? resource.search(query, data)
@@ -266,7 +289,7 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	);
 
 	static copy = transactional(
-		function (resource: Resource, query: Map, _request: Context, data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, data: any) {
 			return resource.copy
 				? resource.constructor.loadAsInstance === false
 					? resource.copy(query, data)
@@ -277,7 +300,7 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	);
 
 	static move = transactional(
-		function (resource: Resource, query: Map, _request: Context, data: any) {
+		function (resource: any, query: RequestTarget, _request: Context, data: any) {
 			return resource.move
 				? resource.constructor.loadAsInstance === false
 					? resource.move(query, data)
@@ -291,14 +314,14 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 		target: RequestTargetOrId,
 		newRecord: Partial<Record & RecordObject>
 	): Promise<Record & Partial<RecordObject>> {
-		if (this.constructor.loadAsInstance === false) {
-			if (target.isCollection && this.create) {
-				newRecord = await this.create(target, newRecord);
-				return newRecord?.[this.constructor.primaryKey];
+		if ((this.constructor as any).loadAsInstance === false) {
+			if ((target as any).isCollection && this.create) {
+				newRecord = (await this.create(target as any, newRecord)) as any;
+				return newRecord?.[(this.constructor as any).primaryKey as keyof typeof newRecord] as any;
 			}
 		} else {
 			if (this.#isCollection) {
-				const resource = await this.constructor.create(this.#id, target, this.#context);
+				const resource = await (this.constructor as any).create(this.#id, target, this.#context);
 				return resource.#id;
 			}
 		}
@@ -327,7 +350,7 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 				// handle path.json, path.cbor, etc. for requesting a specific content type using just the URL
 				context.requestedContentType = requestedContentType;
 				path = path.slice(0, dotIndex); // remove the property from the path
-			} else if (this.attributes?.find((attribute) => attribute.name === property)) {
+			} else if ((this as any).attributes?.find((attribute) => attribute.name === property)) {
 				// handle path.attribute for requesting a specific attribute using just the URL
 				path = path.slice(0, dotIndex); // remove the property from the path
 				if (query) query.property = property;
@@ -355,13 +378,13 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	): Resource | Promise<Resource> {
 		let resource;
 		const id = target.id;
-		let context = request.getContext?.();
+		let context = (request as any).getContext?.();
 		let isCollection;
-		if (typeof request.isCollection === 'boolean' && request.hasOwnProperty('isCollection'))
-			isCollection = request.isCollection;
+		if (typeof (request as any).isCollection === 'boolean' && request.hasOwnProperty('isCollection'))
+			isCollection = (request as any).isCollection;
 		else isCollection = options?.isCollection;
 		// if it is a collection and we have a collection class defined, use it
-		const constructor = (isCollection && this.Collection) || this;
+		const constructor = (isCollection && (this as any).Collection) || this;
 		if (!context) context = context === undefined ? request : {};
 		resource = new constructor(id, context); // outside of a transaction, just create an instance
 		if (isCollection) resource.#isCollection = true;
@@ -374,16 +397,19 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	 * but implementors can call send with
 	 */
 	// eslint-disable-next-line no-unused-vars
-	subscribe(request: SubscriptionRequest): AsyncIterable<Record> {
+	subscribe(request: SubscriptionRequest): AsyncIterable<Record> | Promise<AsyncIterable<Record>> {
 		return new IterableEventQueue();
 	}
 
-	connect(target: RequestTarget, incomingMessages: IterableEventQueue<Record>): AsyncIterable<Record> {
+	connect(
+		target: RequestTarget,
+		incomingMessages: IterableEventQueue<Record>
+	): AsyncIterable<Record> | Promise<AsyncIterable<Record>> {
 		// convert subscription to an (async) iterator
-		const query = this.constructor.loadAsInstance === false ? target : incomingMessages;
-		if (query?.subscribe !== false) {
+		const query = (this.constructor as any).loadAsInstance === false ? target : incomingMessages;
+		if ((query as any)?.subscribe !== false) {
 			// subscribing is the default action, but can be turned off
-			return this.subscribe?.(query);
+			return this.subscribe?.(query as any) as any;
 		}
 		return new IterableEventQueue();
 	}
@@ -439,9 +465,9 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	search?(target: RequestTargetOrId): AsyncIterable<Record & Partial<RecordObject>>;
 
 	create?(
-		newRecord: Partial<Record & RecordObject>,
-		target: RequestTargetOrId
-	): Promise<Record & Partial<RecordObject>>;
+		target: RequestTargetOrId,
+		newRecord: Partial<Record & RecordObject>
+	): void | (Record & Partial<RecordObject>) | Promise<Record & Partial<RecordObject>>;
 	put?(
 		record: Record & RecordObject,
 		target: RequestTargetOrId
@@ -452,7 +478,9 @@ export class Resource<Record extends object = any> implements ResourceInterface<
 	): void | (Record & Partial<RecordObject>) | Promise<void | (Record & Partial<RecordObject>)>;
 
 	delete?(target: RequestTargetOrId): boolean | Promise<boolean>;
-	invalidate?(target: RequestTargetOrId): void | Promise<void>;
+	invalidate(_target: RequestTargetOrId): void | Promise<void> {
+		missingMethod(this, 'invalidate');
+	}
 
 	publish?(target: RequestTargetOrId, record: Record, options?: any): void;
 }
@@ -473,12 +501,15 @@ export function snakeCase(camelCase: string) {
  * @returns
  */
 function transactional(
-	action: (resource: ResourceInterface, query: RequestTarget, context: Context, data: any) => any,
+	action: (resource: any, query: RequestTarget, context: Context, data: any) => any,
 	options: {
-		hasContent: boolean;
+		hasContent?: boolean;
 		type: 'read' | 'update' | 'create' | 'delete';
 		async?: boolean;
 		ensureLoaded?: boolean;
+		letItLinger?: boolean;
+		method?: string;
+		syncAllowed?: boolean;
 	}
 ) {
 	applyContext.reliesOnPrototype = true;
@@ -493,18 +524,23 @@ function transactional(
 			if (context) {
 				// if there are three arguments, it is id, data, context
 				data = dataOrContext;
-				context = context.getContext?.() || context;
+				context = (context as any).getContext?.() || context;
 			} else if (dataOrContext) {
 				// two arguments, more possibilities:
 				if (
 					typeof idOrQuery === 'object' &&
 					idOrQuery &&
+					!(idOrQuery instanceof URLSearchParams) &&
 					(!Array.isArray(idOrQuery) || typeof idOrQuery[0] === 'object')
 				) {
 					// (data, context) form
 					data = idOrQuery;
 					id = data[this.primaryKey] ?? null;
-					context = dataOrContext.getContext?.() || dataOrContext;
+					context = (dataOrContext as any).getContext?.() || dataOrContext;
+					if (context instanceof DatabaseTransaction) context = { transaction: context };
+				} else if (dataOrContext instanceof DatabaseTransaction) {
+					// (id, txn) form
+					context = { transaction: dataOrContext };
 				} else if (dataOrContext?.transaction instanceof DatabaseTransaction) {
 					// (id, context) form
 					context = dataOrContext;
@@ -517,6 +553,10 @@ function transactional(
 				data = idOrQuery;
 				idOrQuery = undefined;
 				id = data.getId?.() ?? data[this.primaryKey];
+			} else if (idOrQuery != null && typeof idOrQuery !== 'object') {
+				// single argument form, just id
+				id = idOrQuery;
+				data = undefined;
 			} else {
 				throw new ClientError(`Invalid argument for data, must be an object, but got ${idOrQuery}`);
 			}
@@ -527,13 +567,13 @@ function transactional(
 			if (context) {
 				// (id, data, context), this a method that doesn't normally have a body/data, but with the three arguments, we have explicit data
 				data = dataOrContext;
-				context = context.getContext?.() || context;
+				context = (context as any).getContext?.() || context;
 			} else if (hasContent === false) {
 				// (id, context), preferred form used for methods that are explicitly without a body
-				context = dataOrContext.getContext?.() || dataOrContext;
+				context = (dataOrContext as any).getContext?.() || dataOrContext;
 			} else if (dataOrContext.transaction || dataOrContext.getContext) {
 				// or if it looks like a context
-				context = dataOrContext.getContext?.() || dataOrContext;
+				context = (dataOrContext as any).getContext?.() || dataOrContext;
 			} else {
 				data = dataOrContext;
 			}
@@ -582,7 +622,7 @@ function transactional(
 						}
 					}
 				} else if (id === undefined) {
-					id = idOrQuery.id ?? null;
+					id = (idOrQuery as any).id ?? null;
 					if (id == null) query.isCollection = true;
 				}
 			} else {
@@ -660,8 +700,8 @@ function transactional(
 								: options.type === 'create'
 									? resource.allowCreate(context.user, data, context)
 									: resource.allowDelete(context.user, query, context);
-					if (allowed?.then) {
-						return allowed.then((allowed) => {
+					if ((allowed as any)?.then) {
+						return (allowed as any).then((allowed) => {
 							query.checkPermission = false;
 							if (!allowed) {
 								throw new AccessViolation(context.user);