@atscript/utils-db 0.1.28

package/dist/index.mjs

@@ -0,0 +1,566 @@
+import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
+
+//#region packages/utils-db/src/logger.ts
+const NoopLogger = {
+	error: () => {},
+	warn: () => {},
+	log: () => {},
+	info: () => {},
+	debug: () => {}
+};
+
+//#endregion
+//#region packages/utils-db/src/patch-types.ts
+function getKeyProps(def) {
+	if (def.type.of.type.kind === "object") {
+		const objType = def.type.of.type;
+		const keyProps = new Set();
+		for (const [key, val] of objType.props.entries()) if (val.metadata.get("expect.array.key")) keyProps.add(key);
+		return keyProps;
+	}
+	return new Set();
+}
+
+//#endregion
+//#region packages/utils-db/src/patch-decomposer.ts
+function decomposePatch(payload, table) {
+	const update = {};
+	const topLevelArrayTag = "db.__topLevelArray";
+	flattenPatchPayload(payload, "", update, table, topLevelArrayTag);
+	return update;
+}
+function flattenPatchPayload(payload, prefix, update, table, topLevelArrayTag) {
+	for (const [_key, value] of Object.entries(payload)) {
+		const key = prefix ? `${prefix}.${_key}` : _key;
+		if (table.primaryKeys.includes(key)) continue;
+		const flatType = table.flatMap.get(key);
+		const isTopLevelArray = flatType?.metadata?.get(topLevelArrayTag);
+		if (typeof value === "object" && value !== null && isTopLevelArray) decomposeArrayPatch(key, value, flatType, update, table);
+else if (typeof value === "object" && value !== null && !Array.isArray(value) && flatType?.metadata?.get("db.patch.strategy") === "merge") flattenPatchPayload(value, key, update, table, topLevelArrayTag);
+else update[key] = value;
+	}
+}
+/**
+* Decomposes array patch operators into simple field updates.
+*
+* For adapters without native array operations, this does a best-effort
+* decomposition:
+* - `$replace` → direct set
+* - `$insert` → value to append (adapter must handle)
+* - `$upsert` → value to upsert by key (adapter must handle)
+* - `$update` → value to update by key (adapter must handle)
+* - `$remove` → value to remove by key (adapter must handle)
+*
+* Note: For full correctness with `$insert`/`$upsert`/`$update`/`$remove`,
+* the adapter should implement native patch support. This generic decomposition
+* handles `$replace` directly and stores the other operations in a structured
+* format the adapter can interpret.
+*/ function decomposeArrayPatch(key, value, fieldType, update, table) {
+	const keyProps = fieldType.type.kind === "array" ? getKeyProps(fieldType) : new Set();
+	if (value.$replace !== undefined) {
+		update[key] = value.$replace;
+		return;
+	}
+	if (value.$insert !== undefined) update[`${key}.__$insert`] = value.$insert;
+	if (value.$upsert !== undefined) {
+		update[`${key}.__$upsert`] = value.$upsert;
+		if (keyProps.size > 0) update[`${key}.__$keys`] = [...keyProps];
+	}
+	if (value.$update !== undefined) {
+		update[`${key}.__$update`] = value.$update;
+		if (keyProps.size > 0) update[`${key}.__$keys`] = [...keyProps];
+	}
+	if (value.$remove !== undefined) {
+		update[`${key}.__$remove`] = value.$remove;
+		if (keyProps.size > 0) update[`${key}.__$keys`] = [...keyProps];
+	}
+}
+
+//#endregion
+//#region packages/utils-db/src/db-table.ts
+function _define_property$1(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+else obj[key] = value;
+	return obj;
+}
+const INDEX_PREFIX = "atscript__";
+function resolveDesignType(fieldType) {
+	if (fieldType.type.kind === "") return fieldType.type.designType ?? "string";
+	if (fieldType.type.kind === "object") return "object";
+	if (fieldType.type.kind === "array") return "array";
+	return "string";
+}
+function indexKey(type, name) {
+	const cleanName = name.replace(/[^a-z0-9_.-]/gi, "_").replace(/_+/g, "_").slice(0, 127 - INDEX_PREFIX.length - type.length - 2);
+	return `${INDEX_PREFIX}${type}__${cleanName}`;
+}
+var AtscriptDbTable = class {
+	/** The raw annotated type. */ get type() {
+		return this._type;
+	}
+	/** Lazily-built flat map of all fields (dot-notation paths → annotated types). */ get flatMap() {
+		this._flatten();
+		return this._flatMap;
+	}
+	/** All computed indexes from `@db.index.*` annotations. */ get indexes() {
+		this._flatten();
+		return this._indexes;
+	}
+	/** Primary key field names from `@meta.id`. */ get primaryKeys() {
+		this._flatten();
+		return this._primaryKeys;
+	}
+	/** Logical → physical column name mapping from `@db.column`. */ get columnMap() {
+		this._flatten();
+		return this._columnMap;
+	}
+	/** Default values from `@db.default.*`. */ get defaults() {
+		this._flatten();
+		return this._defaults;
+	}
+	/** Fields excluded from DB via `@db.ignore`. */ get ignoredFields() {
+		this._flatten();
+		return this._ignoredFields;
+	}
+	/** Single-field unique index properties. */ get uniqueProps() {
+		this._flatten();
+		return this._uniqueProps;
+	}
+	/** Descriptor for the primary ID field(s). */ getIdDescriptor() {
+		this._flatten();
+		return {
+			fields: [...this._primaryKeys],
+			isComposite: this._primaryKeys.length > 1
+		};
+	}
+	/**
+	* Pre-computed field metadata for adapter use.
+	* Filters root entry, resolves designType, physicalName, optional —
+	* encapsulating all the type introspection gotchas.
+	*/ get fieldDescriptors() {
+		this._flatten();
+		if (!this._fieldDescriptors) {
+			this._fieldDescriptors = [];
+			for (const [path, type] of this._flatMap.entries()) {
+				if (!path) continue;
+				this._fieldDescriptors.push({
+					path,
+					type,
+					physicalName: this._columnMap.get(path) ?? path,
+					designType: resolveDesignType(type),
+					optional: type.optional === true,
+					isPrimaryKey: this._primaryKeys.includes(path),
+					ignored: this._ignoredFields.has(path),
+					defaultValue: this._defaults.get(path)
+				});
+			}
+		}
+		return this._fieldDescriptors;
+	}
+	/**
+	* Resolves a projection to a list of field names to include.
+	* - `undefined` → `undefined` (all fields)
+	* - `string[]` → pass through
+	* - `Record<K, 1>` → extract included keys
+	* - `Record<K, 0>` → invert using known field names
+	*/ resolveProjection(projection) {
+		if (!projection) return undefined;
+		if (Array.isArray(projection)) return projection.length > 0 ? projection : undefined;
+		const entries = Object.entries(projection);
+		if (entries.length === 0) return undefined;
+		const firstVal = entries[0][1];
+		if (firstVal === 1) return entries.filter(([, v]) => v === 1).map(([k]) => k);
+		const excluded = new Set(entries.filter(([, v]) => v === 0).map(([k]) => k));
+		return this.fieldDescriptors.filter((f) => !f.ignored && !excluded.has(f.path)).map((f) => f.path);
+	}
+	/**
+	* Creates a new validator with custom options.
+	* Adapter plugins are NOT automatically included — use {@link getValidator}
+	* for the standard validator with adapter plugins.
+	*/ createValidator(opts) {
+		return this._type.validator(opts);
+	}
+	/**
+	* Returns a cached validator for the given purpose.
+	* Built with adapter plugins from {@link BaseDbAdapter.getValidatorPlugins}.
+	*
+	* Standard purposes: `'insert'`, `'update'`, `'patch'`.
+	* Adapters may define additional purposes.
+	*/ getValidator(purpose) {
+		if (!this.validators.has(purpose)) {
+			const validator = this._buildValidator(purpose);
+			this.validators.set(purpose, validator);
+		}
+		return this.validators.get(purpose);
+	}
+	/**
+	* Inserts a single record.
+	* Applies defaults, validates, prepares ID, maps columns, strips ignored fields.
+	*/ async insertOne(payload) {
+		this._flatten();
+		const data = this._applyDefaults({ ...payload });
+		const validator = this.getValidator("insert");
+		if (!validator.validate(data)) throw new Error("Validation failed for insert");
+		return this.adapter.insertOne(this._prepareForWrite(data));
+	}
+	/**
+	* Inserts multiple records.
+	*/ async insertMany(payloads) {
+		this._flatten();
+		const validator = this.getValidator("insert");
+		const prepared = [];
+		for (const payload of payloads) {
+			const data = this._applyDefaults({ ...payload });
+			if (!validator.validate(data)) throw new Error("Validation failed for insert");
+			prepared.push(this._prepareForWrite(data));
+		}
+		return this.adapter.insertMany(prepared);
+	}
+	/**
+	* Replaces a single record identified by primary key(s).
+	* The payload must include primary key field(s).
+	*/ async replaceOne(payload) {
+		this._flatten();
+		const validator = this.getValidator("update");
+		if (!validator.validate(payload)) throw new Error("Validation failed for replace");
+		const filter = this._extractPrimaryKeyFilter(payload);
+		const data = this._prepareForWrite({ ...payload });
+		return this.adapter.replaceOne(filter, data);
+	}
+	/**
+	* Partially updates a single record identified by primary key(s).
+	* Supports array patch operations (`$replace`, `$insert`, `$upsert`,
+	* `$update`, `$remove`) for top-level array fields.
+	*/ async updateOne(payload) {
+		this._flatten();
+		const validator = this.getValidator("patch");
+		if (!validator.validate(payload)) throw new Error("Validation failed for update");
+		const filter = this._extractPrimaryKeyFilter(payload);
+		if (this.adapter.supportsNativePatch()) return this.adapter.nativePatch(filter, payload);
+		const update = decomposePatch(payload, this);
+		return this.adapter.updateOne(filter, update);
+	}
+	/**
+	* Deletes a single record by primary key value.
+	*/ async deleteOne(id) {
+		this._flatten();
+		const pkFields = this.primaryKeys;
+		if (pkFields.length === 0) throw new Error("No primary key defined — cannot delete by ID");
+		const filter = {};
+		if (pkFields.length === 1) {
+			const field = pkFields[0];
+			const fieldType = this.flatMap.get(field);
+			filter[field] = fieldType ? this.adapter.prepareId(id, fieldType) : id;
+		} else {
+			const idObj = id;
+			for (const field of pkFields) {
+				const fieldType = this.flatMap.get(field);
+				filter[field] = fieldType ? this.adapter.prepareId(idObj[field], fieldType) : idObj[field];
+			}
+		}
+		return this.adapter.deleteOne(filter);
+	}
+	/**
+	* Finds a single record matching the filter.
+	*/ async findOne(filter, options) {
+		return this.adapter.findOne(filter, options);
+	}
+	/**
+	* Finds all records matching the filter.
+	*/ async findMany(filter, options) {
+		return this.adapter.findMany(filter, options);
+	}
+	/**
+	* Counts records matching the filter.
+	*/ async count(filter = {}) {
+		return this.adapter.count(filter);
+	}
+	async updateMany(filter, data) {
+		return this.adapter.updateMany(filter, data);
+	}
+	async replaceMany(filter, data) {
+		return this.adapter.replaceMany(filter, data);
+	}
+	async deleteMany(filter) {
+		return this.adapter.deleteMany(filter);
+	}
+	/**
+	* Synchronizes indexes between Atscript definitions and the database.
+	* Delegates to the adapter, which uses `this._table.indexes`.
+	*/ async syncIndexes() {
+		this._flatten();
+		return this.adapter.syncIndexes();
+	}
+	/**
+	* Ensures the table/collection exists in the database.
+	*/ async ensureTable() {
+		this._flatten();
+		return this.adapter.ensureTable();
+	}
+	_flatten() {
+		if (this._flatMap) return;
+		this.adapter.onBeforeFlatten?.(this._type);
+		this._flatMap = flattenAnnotatedType(this.type, {
+			topLevelArrayTag: this.adapter.getTopLevelArrayTag?.() ?? "db.__topLevelArray",
+			excludePhantomTypes: true,
+			onField: (path, type, metadata) => {
+				this._scanGenericAnnotations(path, metadata);
+				this.adapter.onFieldScanned?.(path, type, metadata);
+			}
+		});
+		this._finalizeIndexes();
+		this.adapter.onAfterFlatten?.();
+	}
+	/**
+	* Scans `@db.*` and `@meta.id` annotations on a field during flattening.
+	*/ _scanGenericAnnotations(fieldName, metadata) {
+		if (metadata.has("meta.id")) this._primaryKeys.push(fieldName);
+		const column = metadata.get("db.column");
+		if (column) this._columnMap.set(fieldName, column);
+		const defaultValue = metadata.get("db.default.value");
+		const defaultFn = metadata.get("db.default.fn");
+		if (defaultValue !== undefined) this._defaults.set(fieldName, {
+			kind: "value",
+			value: defaultValue
+		});
+else if (defaultFn !== undefined) this._defaults.set(fieldName, {
+			kind: "fn",
+			fn: defaultFn
+		});
+		if (metadata.has("db.ignore")) this._ignoredFields.add(fieldName);
+		for (const index of metadata.get("db.index.plain") || []) {
+			const name = index === true ? fieldName : index?.name || fieldName;
+			const sort = (index === true ? undefined : index?.sort) || "asc";
+			this._addIndexField("plain", name, fieldName, sort);
+		}
+		for (const index of metadata.get("db.index.unique") || []) {
+			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
+			this._addIndexField("unique", name, fieldName);
+		}
+		for (const index of metadata.get("db.index.fulltext") || []) {
+			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
+			this._addIndexField("fulltext", name, fieldName);
+		}
+	}
+	_addIndexField(type, name, field, sort = "asc") {
+		const key = indexKey(type, name);
+		const index = this._indexes.get(key);
+		const indexField = {
+			name: field,
+			sort
+		};
+		if (index) index.fields.push(indexField);
+else this._indexes.set(key, {
+			key,
+			name,
+			type,
+			fields: [indexField]
+		});
+	}
+	_finalizeIndexes() {
+		for (const index of this._indexes.values()) if (index.type === "unique" && index.fields.length === 1) this._uniqueProps.add(index.fields[0].name);
+	}
+	/**
+	* Applies default values for fields that are missing from the payload.
+	* Called before validation so that defaults satisfy required field constraints.
+	*/ _applyDefaults(data) {
+		for (const [field, def] of this._defaults.entries()) if (data[field] === undefined) {
+			if (def.kind === "value") data[field] = def.value;
+		}
+		return data;
+	}
+	/**
+	* Prepares a payload for writing to the database:
+	* prepares IDs, strips ignored fields, maps column names.
+	* Defaults should be applied before this via `_applyDefaults`.
+	*/ _prepareForWrite(payload) {
+		const data = { ...payload };
+		for (const pk of this._primaryKeys) if (data[pk] !== undefined) {
+			const fieldType = this._flatMap?.get(pk);
+			if (fieldType) data[pk] = this.adapter.prepareId(data[pk], fieldType);
+		}
+		for (const field of this._ignoredFields) delete data[field];
+		for (const [logical, physical] of this._columnMap.entries()) if (logical in data) {
+			data[physical] = data[logical];
+			delete data[logical];
+		}
+		return data;
+	}
+	/**
+	* Extracts primary key field(s) from a payload to build a filter.
+	*/ _extractPrimaryKeyFilter(payload) {
+		const pkFields = this.primaryKeys;
+		if (pkFields.length === 0) throw new Error("No primary key defined — cannot extract filter");
+		const filter = {};
+		for (const field of pkFields) {
+			if (payload[field] === undefined) throw new Error(`Missing primary key field "${field}" in payload`);
+			const fieldType = this.flatMap.get(field);
+			filter[field] = fieldType ? this.adapter.prepareId(payload[field], fieldType) : payload[field];
+		}
+		return filter;
+	}
+	/**
+	* Builds a validator for a given purpose with adapter plugins.
+	*/ _buildValidator(purpose) {
+		const plugins = this.adapter.getValidatorPlugins();
+		switch (purpose) {
+			case "insert": return this.createValidator({
+				plugins,
+				replace: (type, path) => {
+					if (this._primaryKeys.includes(path)) return {
+						...type,
+						optional: true
+					};
+					return type;
+				}
+			});
+			case "update": return this.createValidator({ plugins });
+			case "patch": return this.createValidator({
+				plugins,
+				partial: true
+			});
+			default: return this.createValidator({ plugins });
+		}
+	}
+	constructor(_type, adapter, logger = NoopLogger) {
+		_define_property$1(this, "_type", void 0);
+		_define_property$1(this, "adapter", void 0);
+		_define_property$1(this, "logger", void 0);
+		/** Resolved table/collection name. */ _define_property$1(this, "tableName", void 0);
+		/** Database schema/namespace from `@db.schema` (if set). */ _define_property$1(this, "schema", void 0);
+		_define_property$1(this, "_flatMap", void 0);
+		_define_property$1(this, "_fieldDescriptors", void 0);
+		_define_property$1(this, "_indexes", void 0);
+		_define_property$1(this, "_primaryKeys", void 0);
+		_define_property$1(this, "_columnMap", void 0);
+		_define_property$1(this, "_defaults", void 0);
+		_define_property$1(this, "_ignoredFields", void 0);
+		_define_property$1(this, "_uniqueProps", void 0);
+		_define_property$1(this, "validators", void 0);
+		this._type = _type;
+		this.adapter = adapter;
+		this.logger = logger;
+		this._indexes = new Map();
+		this._primaryKeys = [];
+		this._columnMap = new Map();
+		this._defaults = new Map();
+		this._ignoredFields = new Set();
+		this._uniqueProps = new Set();
+		this.validators = new Map();
+		if (!isAnnotatedType(_type)) throw new Error("Atscript Annotated Type expected");
+		if (_type.type.kind !== "object") throw new Error("Database table type must be an object type");
+		const adapterName = adapter.getAdapterTableName?.(_type);
+		const dbTable = _type.metadata.get("db.table");
+		const fallbackName = _type.id || "";
+		this.tableName = adapterName || dbTable || fallbackName;
+		if (!this.tableName) throw new Error("@db.table annotation or adapter-specific table name expected");
+		this.schema = _type.metadata.get("db.schema");
+		adapter.registerTable(this);
+	}
+};
+
+//#endregion
+//#region packages/utils-db/src/base-adapter.ts
+function _define_property(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+else obj[key] = value;
+	return obj;
+}
+var BaseDbAdapter = class {
+	/**
+	* Called by {@link AtscriptDbTable} constructor. Gives the adapter access to
+	* the table's computed metadata for internal use in query rendering, index
+	* sync, etc.
+	*/ registerTable(table) {
+		this._table = table;
+	}
+	/**
+	* Returns additional validator plugins for this adapter.
+	* These are merged with the built-in Atscript validators.
+	*
+	* Example: MongoDB adapter returns ObjectId validation plugin.
+	*/ getValidatorPlugins() {
+		return [];
+	}
+	/**
+	* Transforms an ID value for the database.
+	* Override to convert string → ObjectId, parse numeric IDs, etc.
+	*
+	* @param id - The raw ID value.
+	* @param fieldType - The annotated type of the ID field.
+	* @returns The transformed ID value.
+	*/ prepareId(id, fieldType) {
+		return id;
+	}
+	/**
+	* Whether this adapter supports native patch operations.
+	* When `true`, {@link AtscriptDbTable} delegates patch payloads to
+	* {@link nativePatch} instead of using the generic decomposition.
+	*/ supportsNativePatch() {
+		return false;
+	}
+	/**
+	* Applies a patch payload using native database operations.
+	* Only called when {@link supportsNativePatch} returns `true`.
+	*
+	* @param filter - Filter identifying the record to patch.
+	* @param patch - The patch payload with array operations.
+	* @returns Update result.
+	*/ async nativePatch(filter, patch) {
+		throw new Error("Native patch not supported by this adapter");
+	}
+	/**
+	* Resolves the full table name, optionally including the schema prefix.
+	* Override for databases that don't support schemas (e.g., SQLite).
+	*
+	* @param includeSchema - Whether to prepend `schema.` prefix (default: true).
+	*/ resolveTableName(includeSchema = true) {
+		const schema = this._table.schema;
+		const name = this._table.tableName;
+		return includeSchema && schema ? `${schema}.${name}` : name;
+	}
+	/**
+	* Template method for index synchronization.
+	* Implements the diff algorithm (list → compare → create/drop).
+	* Adapters provide the three DB-specific primitives.
+	*
+	* @example
+	* ```typescript
+	* async syncIndexes() {
+	*   await this.syncIndexesWithDiff({
+	*     listExisting: async () => this.driver.all('PRAGMA index_list(...)'),
+	*     createIndex: async (index) => this.driver.exec('CREATE INDEX ...'),
+	*     dropIndex: async (name) => this.driver.exec('DROP INDEX ...'),
+	*     shouldSkipType: (type) => type === 'fulltext',
+	*   })
+	* }
+	* ```
+	*/ async syncIndexesWithDiff(opts) {
+		const prefix = opts.prefix ?? "atscript__";
+		const existing = await opts.listExisting();
+		const existingNames = new Set(existing.filter((i) => i.name.startsWith(prefix)).map((i) => i.name));
+		const desiredNames = new Set();
+		for (const index of this._table.indexes.values()) {
+			if (opts.shouldSkipType?.(index.type)) continue;
+			desiredNames.add(index.key);
+			if (!existingNames.has(index.key)) await opts.createIndex(index);
+		}
+		for (const name of existingNames) if (!desiredNames.has(name)) await opts.dropIndex(name);
+	}
+	constructor() {
+		_define_property(this, "_table", void 0);
+	}
+};
+
+//#endregion
+export { AtscriptDbTable, BaseDbAdapter, NoopLogger, decomposePatch, getKeyProps, resolveDesignType };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@atscript/utils-db",
+  "version": "0.1.28",
+  "description": "Database adapter utilities for atscript.",
+  "keywords": [
+    "atscript",
+    "database",
+    "utils"
+  ],
+  "homepage": "https://github.com/moostjs/atscript/tree/main/packages/utils-db#readme",
+  "bugs": {
+    "url": "https://github.com/moostjs/atscript/issues"
+  },
+  "license": "ISC",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/atscript.git",
+    "directory": "packages/utils-db"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "vitest": "3.2.4"
+  },
+  "peerDependencies": {
+    "@atscript/core": "^0.1.28",
+    "@atscript/typescript": "^0.1.28"
+  },
+  "scripts": {
+    "pub": "pnpm publish --access public",
+    "test": "vitest"
+  }
+}