@prostojs/mate 0.3.3 → 0.5.0

package/README.md

@@ -19,27 +19,27 @@ npm install @prostojs/mate
 After installation, you can start using Mate to define and handle metadata in your TypeScript project. Below is an example that showcases different levels of metadata usage.
 
 ```ts
-import { TMateParamMeta } from '@prostojs/mate';
-import { Mate } from '@prostojs/mate';
+import { TMateParamMeta } from '@prostojs/mate'
+import { Mate } from '@prostojs/mate'
 
 // Define your metadata interfaces
 interface TClassMeta {
-    name: string;
-    model: string;
-    fromParam: string;
-    manufacturer: string;
-    data: string[];
-    inherit?: bolean;
+    name: string
+    model: string
+    fromParam: string
+    manufacturer: string
+    data: string[]
+    inherit?: bolean
 }
 
 interface TPropMeta<TParamMeta> {
-    description: string;
-    params: (TMateParamMeta & TParamMeta)[];
+    description: string
+    params: (TMateParamMeta & TParamMeta)[]
     inherit?: bolean
 }
 
 interface TParamMeta {
-    required: boolean;
+    required: boolean
 }
 
 const mate = new Mate<TClassMeta, TPropMeta<TParamMeta>>('robot-meta', {
@@ -47,32 +47,32 @@ const mate = new Mate<TClassMeta, TPropMeta<TParamMeta>>('robot-meta', {
     readType: true,
     collectPropKeys: true,
     inherit(classMeta, targetMeta, level, prop) {
-        return !!targetMeta?.inherit || !!classMeta?.inherit;
+        return !!targetMeta?.inherit || !!classMeta?.inherit
     },
-});
+})
 
 // Annotate your class
-@mate.decorate('name', 'NXT') 
-@mate.decorate('model', 'EV3') 
+@mate.decorate('name', 'NXT')
+@mate.decorate('model', 'EV3')
 @mate.decorate('manufacturer', 'LEGO')
-@mate.decorate('data', 'NXT-0001', true)  
+@mate.decorate('data', 'NXT-0001', true)
 class Robot {
     @mate.decorate('description', 'Robotic arm for grabbing objects')
-    arm: string;
+    arm: string
 
-    @mate.decorate('description', 'Sensors to detect objects') 
+    @mate.decorate('description', 'Sensors to detect objects')
     sensors(
-        @mate.decorateClass('fromParam', 'hoised value')  
-        @mate.decorate('required', true) 
-        input: string
+        @mate.decorateClass('fromParam', 'hoised value')
+        @mate.decorate('required', true)
+        input: string,
     ): string {
-        return 'Activated sensors with input: ' + input;
+        return 'Activated sensors with input: ' + input
     }
 }
 
 // Read the metadata
-let classMeta = mate.read(Robot);
-console.log(classMeta);
+let classMeta = mate.read(Robot)
+console.log(classMeta)
 // Expected Output:
 // {
 //     name: 'NXT',
@@ -86,8 +86,8 @@ console.log(classMeta);
 // }
 
 // read the property metadata
-let armMeta = mate.read(Robot, 'arm');
-console.log(armMeta);
+let armMeta = mate.read(Robot, 'arm')
+console.log(armMeta)
 // Expected Output:
 // {
 //     description: 'Robotic arm for grabbing objects',
@@ -97,8 +97,8 @@ console.log(armMeta);
 // }
 
 // read the method metadata
-let sensorsMeta = mate.read(Robot, 'sensors');
-console.log(sensorsMeta);
+let sensorsMeta = mate.read(Robot, 'sensors')
+console.log(sensorsMeta)
 // Expected Output:
 // {
 //     description: 'Sensors to detect objects',
@@ -132,12 +132,14 @@ const mate = new Mate<MyMeta>('my-metadata-key', {
         if (prop) {
             // if it is a method metadata
             // we require a key `inherit` to be true for inheritance
-            return !!methodMeta?.inherit || !!(classMeta?.inherit && !methodMeta)
+            return (
+                !!methodMeta?.inherit || !!(classMeta?.inherit && !methodMeta)
+            )
         }
         // otherwise (in case of class metadata) we require a key `inherit`
         // to be true for inheritance on class metadata
         return !!classMeta?.inherit
-    }
+    },
 })
 ```
 

package/dist/index.cjs

@@ -0,0 +1,242 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/module-identity.ts
+const MATE_MODULE_IDENTITY_KEY = Symbol.for("prostojs:mate:module-identity");
+function getModulePath() {
+	try {
+		return require("url").pathToFileURL(__filename).href;
+	} catch {
+		return;
+	}
+}
+function formatIdentity(identity) {
+	const version = identity.version ? `v${identity.version}` : "unknown version";
+	return identity.path ? `${version} at ${identity.path}` : version;
+}
+/**
+* Stamps `globalThis` with this copy's identity and warns if another
+* copy of @prostojs/mate was already loaded.
+*
+* Invoked once at module scope from index.ts, so importing the package
+* performs the check.
+*/
+function warnOnDuplicateMate() {
+	const g = globalThis;
+	const identity = {};
+	identity.version = "0.4.0";
+	const path = getModulePath();
+	if (path) identity.path = path;
+	const first = g[MATE_MODULE_IDENTITY_KEY];
+	if (first) console.warn(`[mate] A second copy of @prostojs/mate was loaded (${formatIdentity(first)}, now ${formatIdentity(identity)}). Decorator metadata is stored per-copy and will NOT be visible across copies. Check your bundler/dedupe settings.`);
+	else g[MATE_MODULE_IDENTITY_KEY] = identity;
+}
+
+//#endregion
+//#region src/utils/helpers.ts
+function getConstructor(instance) {
+	return isConstructor(instance) ? instance : instance.constructor ? instance.constructor : Object.getPrototypeOf(instance).constructor;
+}
+function isConstructor(v) {
+	return typeof v === "function" && Object.getOwnPropertyDescriptor(v, "prototype") !== void 0 && Object.getOwnPropertyDescriptor(v, "caller") === void 0 && !!v.name;
+}
+
+//#endregion
+//#region src/reflect.ts
+let classMetadata = /* @__PURE__ */ new WeakMap();
+let paramMetadata = /* @__PURE__ */ new WeakMap();
+const root = typeof global === "object" ? global : typeof self === "object" ? self : {};
+function getMetaObject(target, prop) {
+	const isParam = typeof prop !== "undefined";
+	const metadata = isParam ? paramMetadata : classMetadata;
+	const targetKey = getConstructor(target);
+	let meta = metadata.get(targetKey);
+	if (!meta) {
+		meta = {};
+		metadata.set(targetKey, meta);
+	}
+	if (isParam) meta = meta[prop] = meta[prop] || {};
+	return meta;
+}
+const _reflect = {
+	getOwnMetadata(key, target, prop) {
+		return getMetaObject(target, prop)[key];
+	},
+	defineMetadata(key, data, target, prop) {
+		const meta = getMetaObject(target, prop);
+		meta[key] = data;
+	},
+	metadata(key, data) {
+		return ((target, propKey) => {
+			Reflect$1.defineMetadata(key, data, target, propKey);
+		});
+	},
+	_cleanup: (() => {
+		classMetadata = /* @__PURE__ */ new WeakMap();
+		paramMetadata = /* @__PURE__ */ new WeakMap();
+	})
+};
+if (!root.Reflect) root.Reflect = _reflect;
+else {
+	const funcs = [
+		"getOwnMetadata",
+		"defineMetadata",
+		"metadata"
+	];
+	const target = root.Reflect;
+	for (const func of funcs) if (typeof target[func] !== "function") Object.defineProperty(target, func, {
+		configurable: true,
+		writable: true,
+		value: _reflect[func]
+	});
+}
+const Reflect$1 = _reflect;
+
+//#endregion
+//#region src/mate.ts
+const Reflect = global?.Reflect || self?.Reflect || Reflect$1;
+var Mate = class {
+	constructor(workspace, options = {}) {
+		this.workspace = workspace;
+		this.options = options;
+		this.logger = options.logger || console;
+	}
+	/**
+	* Cleanup function to reset metadata
+	*
+	* It is usefull in dev mode when server restarts
+	*/
+	_cleanup() {
+		Reflect._cleanup?.call(Reflect);
+		this._readCache = void 0;
+	}
+	set(args, key, value, isArray) {
+		this._readCache = void 0;
+		let level = "CLASS";
+		const newArgs = args.level === "CLASS" ? { target: getConstructor(args.target) } : args.level === "PROP" ? {
+			target: args.target,
+			propKey: args.propKey
+		} : args;
+		let meta = Reflect.getOwnMetadata(this.workspace, newArgs.target, newArgs.propKey) || {};
+		if (newArgs.propKey && this.options.readReturnType && !meta.returnType && args.descriptor) meta.returnType = Reflect.getOwnMetadata("design:returntype", newArgs.target, newArgs.propKey);
+		if (newArgs.propKey && this.options.readType && !meta.type) meta.type = Reflect.getOwnMetadata("design:type", newArgs.target, newArgs.propKey);
+		const { index } = newArgs;
+		const cb = typeof key === "function" ? key : void 0;
+		let data = meta;
+		if (!data.params) {
+			const paramTypes = Reflect.getOwnMetadata("design:paramtypes", newArgs.target, newArgs.propKey);
+			if (paramTypes) {
+				data.params = new Array(paramTypes.length);
+				for (let i = 0; i < paramTypes.length; i++) data.params[i] = { type: paramTypes[i] };
+			}
+		}
+		if (typeof index === "number") {
+			level = "PARAM";
+			data.params = data.params || [];
+			data.params[index] = data.params[index] || { type: void 0 };
+			if (cb) data.params[index] = cb(data.params[index], level, args.propKey, typeof args.index === "number" ? args.index : void 0);
+			else data = data.params[index];
+		} else if (!index && !args.descriptor && args.propKey && this.options.collectPropKeys && args.level !== "CLASS") this.set({
+			...args,
+			level: "CLASS"
+		}, (meta) => {
+			if (!meta.properties) meta.properties = [args.propKey];
+			else if (!meta.properties.includes(args.propKey)) meta.properties.push(args.propKey);
+			return meta;
+		});
+		level = typeof index === "number" ? "PARAM" : newArgs.propKey && newArgs.descriptor ? "METHOD" : newArgs.propKey ? "PROP" : "CLASS";
+		if (typeof key !== "function") if (isArray) {
+			const newArray = data[key] || [];
+			if (!Array.isArray(newArray))
+ /* istanbul ignore next line */
+			this.logger.error("Mate.add (isArray=true) called for non-array metadata");
+			newArray.unshift(value);
+			data[key] = newArray;
+		} else data[key] = value;
+		else if (cb && typeof index !== "number") meta = cb(data, level, args.propKey, typeof args.index === "number" ? args.index : void 0);
+		Reflect.defineMetadata(this.workspace, meta, newArgs.target, newArgs.propKey);
+	}
+	read(target, propKey) {
+		const constructor = isConstructor(target) ? target : getConstructor(target);
+		const proto = constructor.prototype;
+		const propKeyStr = propKey;
+		const ctorCache = this._readCache?.get(constructor);
+		if (ctorCache?.has(propKeyStr)) return ctorCache.get(propKeyStr);
+		let ownMeta = Reflect.getOwnMetadata(this.workspace, typeof propKey === "string" ? proto : constructor, propKey);
+		if (ownMeta && propKey === void 0 && ownMeta.params === void 0) {
+			const parent = Object.getPrototypeOf(constructor);
+			if (typeof parent === "function" && parent !== fnProto && parent !== constructor) ownMeta.params = this.read(parent)?.params;
+		}
+		if (this.options.inherit) {
+			const inheritFn = typeof this.options.inherit === "function" ? this.options.inherit : void 0;
+			let shouldInherit = this.options.inherit;
+			if (inheritFn) if (typeof propKey === "string") shouldInherit = inheritFn(Reflect.getOwnMetadata(this.workspace, constructor), ownMeta, "PROP", propKey);
+			else shouldInherit = inheritFn(ownMeta, ownMeta, "CLASS");
+			if (shouldInherit) {
+				const parent = Object.getPrototypeOf(constructor);
+				if (typeof parent === "function" && parent !== fnProto && parent !== constructor) {
+					const inheritedMeta = this.read(parent, propKey) || {};
+					const ownParams = ownMeta?.params;
+					ownMeta = {
+						...inheritedMeta,
+						...ownMeta
+					};
+					if (typeof propKey === "string" && ownParams && inheritedMeta?.params) {
+						for (let i = 0; i < ownParams.length; i++) if (typeof inheritedMeta?.params[i] !== "undefined") {
+							const ownParam = ownParams[i];
+							if (ownMeta.params && inheritFn && inheritFn(ownMeta, ownParam, "PARAM", typeof propKey === "string" ? propKey : void 0)) ownMeta.params[i] = {
+								...inheritedMeta?.params[i],
+								...ownParams[i]
+							};
+						}
+					}
+				}
+			}
+		}
+		const cache = this._readCache ??= /* @__PURE__ */ new WeakMap();
+		let tc = cache.get(constructor);
+		if (!tc) {
+			tc = /* @__PURE__ */ new Map();
+			cache.set(constructor, tc);
+		}
+		tc.set(propKeyStr, ownMeta);
+		return ownMeta;
+	}
+	apply(...decorators) {
+		return ((target, propKey, descriptor) => {
+			for (const d of decorators) d(target, propKey, descriptor);
+		});
+	}
+	decorate(key, value, isArray, level) {
+		return ((target, propKey, descriptor) => {
+			const args = {
+				target,
+				propKey,
+				descriptor: typeof descriptor === "number" ? void 0 : descriptor,
+				index: typeof descriptor === "number" ? descriptor : void 0,
+				level
+			};
+			this.set(args, key, value, isArray);
+		});
+	}
+	decorateConditional(ccb) {
+		return ((target, propKey, descriptor) => {
+			const d = ccb(typeof descriptor === "number" ? "PARAM" : propKey && descriptor ? "METHOD" : propKey ? "PROP" : "CLASS");
+			if (d) d(target, propKey, descriptor);
+		});
+	}
+	decorateClass(key, value, isArray) {
+		return this.decorate(key, value, isArray, "CLASS");
+	}
+};
+const fnProto = Object.getPrototypeOf(Function);
+
+//#endregion
+//#region src/index.ts
+warnOnDuplicateMate();
+
+//#endregion
+exports.MATE_MODULE_IDENTITY_KEY = MATE_MODULE_IDENTITY_KEY;
+exports.Mate = Mate;
+exports.getConstructor = getConstructor;
+exports.isConstructor = isConstructor;
+exports.warnOnDuplicateMate = warnOnDuplicateMate;

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+//#region dts-build/types.d.ts
+type TAny = any;
+type TObject = object;
+type TFunction = Function;
+type TClassConstructor<T = unknown> = new (...args: TAny[]) => T;
+//#endregion
+//#region dts-build/mate.d.ts
+type TLevels = 'CLASS' | 'METHOD' | 'PROP' | 'PARAM';
+interface TMergedDecoratorArgs {
+  target: TFunction | TObject;
+  propKey?: string;
+  descriptor?: TypedPropertyDescriptor<TAny>;
+  index?: number;
+  level?: TLevels;
+}
+interface TMateParamMeta {
+  type?: TFunction;
+}
+interface TMatePropMeta<TParam extends TObject = TEmpty> {
+  params?: (TParam & TMateParamMeta)[];
+}
+interface TMateClassMeta<TParam> {
+  properties?: string[];
+  type?: TFunction;
+  returnType?: TFunction;
+  params?: (TParam & TMateParamMeta)[];
+}
+type TCommonMate<TParam extends TObject> = TMateClassMeta<TParam> & TMatePropMeta<TParam>;
+type TCommonMateWithParam<TParam extends TObject> = TMateClassMeta<TParam> & TMatePropMeta<TParam> & TParam;
+interface TConsoleBase {
+  error: (...args: any) => void;
+}
+interface TMateOptions<TClass extends TObject = TMateClassMeta<TMateParamMeta>, TProp extends {
+  params: TMateParamMeta[];
+} = Required<TMatePropMeta<TMateParamMeta>>> {
+  logger?: TConsoleBase;
+  readReturnType?: boolean;
+  readType?: boolean;
+  collectPropKeys?: boolean;
+  inherit?: boolean | ((classMeta: TClass & TMateClassMeta<TMateParamMeta>, targetMeta: (TMatePropMeta<TProp['params'][0]> & TProp) | (TMateParamMeta & TProp['params'][0]), level: 'CLASS' | 'PROP' | 'PARAM', key?: string) => boolean);
+}
+interface TEmpty {}
+declare class Mate<TClass extends TObject = TMateClassMeta<TMateParamMeta>, TProp extends {
+  params: TMateParamMeta[];
+} = Required<TMatePropMeta<TMateParamMeta>>> {
+  protected workspace: string;
+  protected options: TMateOptions<TClass, TProp>;
+  protected logger: TConsoleBase;
+  protected _readCache?: WeakMap<object, Map<string | undefined, unknown>>;
+  constructor(workspace: string, options?: TMateOptions<TClass, TProp>);
+  /**
+   * Cleanup function to reset metadata
+   *
+   * It is usefull in dev mode when server restarts
+   */
+  _cleanup(): void;
+  set<T = TClass & TProp & TCommonMateWithParam<TProp['params'][0]>>(args: TMergedDecoratorArgs, cb: (meta: T, level: TLevels, propKey?: string, index?: number) => T): void;
+  set<T = TClass & TProp & TCommonMateWithParam<TProp['params'][0]>, K extends keyof T = keyof T>(args: TMergedDecoratorArgs, key: keyof T, value: T[K]): void;
+  set<T = TClass & TProp & TCommonMateWithParam<TProp['params'][0]>, K extends keyof T = keyof T>(args: TMergedDecoratorArgs, key: keyof T, value: T[K], isArray: boolean | undefined): void;
+  read<PK>(target: TFunction | TObject, propKey?: PK): PK extends string ? (TClass & TProp & TCommonMate<TProp['params'][0]>) | undefined : TClass | undefined;
+  apply(...decorators: (MethodDecorator | ClassDecorator | ParameterDecorator | PropertyDecorator)[]): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+  decorate<T = TClass & TProp & TCommonMateWithParam<TProp['params'][0]>>(cb: (meta: T, level: TLevels, propKey?: string, index?: number) => T): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+  decorate<T = TClass & TProp & TCommonMateWithParam<TProp['params'][0]>, K extends keyof T = keyof T>(key: K, value: T[K]): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+  decorate<T = TClass & TProp & TCommonMateWithParam<TProp['params'][0]>, K extends keyof T = keyof T, TIsArray extends boolean = false>(key: K, value: TIsArray extends true ? ArrayElementType<T[K]> : T[K], isArray: TIsArray): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+  decorate<T = TClass & TProp & TCommonMateWithParam<TProp['params'][0]>, K extends keyof T = keyof T, TIsArray extends boolean = false>(key: K | ((meta: T, level: TLevels, propKey?: string, index?: number) => T), value: TIsArray extends true ? ArrayElementType<T[K]> : T[K], isArray: TIsArray, level: TMergedDecoratorArgs['level']): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+  decorateConditional(ccb: (level: TLevels) => (MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator) | void | undefined): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+  decorateClass<T = TClass>(cb: (meta: T, level: TLevels, propKey?: string, index?: number) => T): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+  decorateClass<T = TClass, K extends keyof T = keyof T, TIsArray extends boolean = false>(key: K, value: TIsArray extends true ? ArrayElementType<T[K]> : T[K]): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+  decorateClass<T = TClass, K extends keyof T = keyof T, TIsArray extends boolean = false>(key: K, value: TIsArray extends true ? ArrayElementType<T[K]> : T[K], isArray: boolean | undefined): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+}
+type ArrayElementType<T> = T extends (infer E)[] ? E : never;
+//#endregion
+//#region dts-build/module-identity.d.ts
+/**
+ * Duplicate-copy detection for @prostojs/mate
+ *
+ * Mate stores class metadata in WeakMaps keyed by constructor reference.
+ * If a bundler loads two copies of mate (or of a decorated class),
+ * decorators run against one copy while lookups hit the other, and
+ * metadata silently "disappears". The first loaded copy stamps
+ * `globalThis` under a global symbol; any subsequent copy finds the
+ * stamp and warns.
+ */
+interface TMateModuleIdentity {
+  version?: string;
+  path?: string;
+}
+declare const MATE_MODULE_IDENTITY_KEY: unique symbol;
+/**
+ * Stamps `globalThis` with this copy's identity and warns if another
+ * copy of @prostojs/mate was already loaded.
+ *
+ * Invoked once at module scope from index.ts, so importing the package
+ * performs the check.
+ */
+declare function warnOnDuplicateMate(): void;
+//#endregion
+//#region dts-build/utils/helpers.d.ts
+declare function getConstructor<T = TAny>(instance: T): TFunction;
+declare function isConstructor<T = TAny>(v: T): v is T & TClassConstructor;
+//#endregion
+export { MATE_MODULE_IDENTITY_KEY, Mate, TMateClassMeta, TMateModuleIdentity, TMateOptions, TMateParamMeta, TMatePropMeta, TMergedDecoratorArgs, getConstructor, isConstructor, warnOnDuplicateMate };