@so0shka/ts-mask 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 So0shka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# TypeScript Mask Library
+
+A simple library to define and infer types for object fields using "masks" in TypeScript. This library allows you to specify which fields of an object should be selected, while automatically inferring the corresponding types.
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install ts-mask
+```
+
+## Usage
+
+Comprehensive example:
+
+```ts
+import { createMask, MaskInfer } from "ts-mask";
+
+interface IDocument {
+  id: number;
+  number: string;
+  author: {
+    id: number;
+    fullname: string;
+  };
+  items: {
+    name: string;
+    description: string;
+  }[];
+}
+
+const productMask = createMask((p: MaskProvider<IDocument>) => [
+  p.id,
+  p.author,
+  p.items.mask((i) => [i.name]),
+]);
+
+productMask.toObject();
+
+// {
+//   id: Symbol(MARKED),
+//   author: Symbol(MARKED),
+//   items: {
+//     name: Symbol(MARKED),
+//   }
+// }
+
+type PartialProduct = MaskInfer<typeof productMask>;
+// type PartialProduct = {
+//   id: number;
+//   author: {
+//     id: number;
+//     fullname: string;
+//   };
+//   items: {
+//     name: string;
+//   }[];
+// };
+```
+
+## API
+
+### createMask function
+
+Creates a mask for a given object type. It accepts a builder function that defines which fields should be included in the mask.
+
+The created mask has a `toObject` method that returns the object representation of the mask, where each field is marked with a `markedSymbol`.
+
+#### Example:
+
+```
+const mask = createMask((p: MaskProvider<MyObject>) => [p.field1, p.field2]);
+mask.toObject();
+```
+
+### MaskInfer type
+
+This utility type is used to infer the partial type of the object based on the mask created by `createMask`.
+
+#### Example:
+
+```
+type MyObjectPartial = MaskInfer<typeof mask>;
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const MarkedSymbol: unique symbol;
+export type MarkedSymbolType = typeof MarkedSymbol;

package/dist/constants.js

@@ -0,0 +1 @@
+export const MarkedSymbol = Symbol("MARKED");

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,YAAY,GAAkB,MAAM,CAAC,QAAQ,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { MarkedSymbol } from "./constants.js";
+export { createMask } from "./utils.js";
+export { IMask, MaskInfer, MaskTree, MaskProvider } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { MarkedSymbol } from "./constants.js";
+export { createMask } from "./utils.js";

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+import { MarkedSymbolType } from "./constants.js";
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type NonFunctionPropertyNames<T> = {
+    [K in keyof T]: T[K] extends Function ? never : K;
+}[keyof T];
+type NonFunctionProperties<T> = Pick<T, NonFunctionPropertyNames<T>>;
+type ValidKeys<ObjectT> = Extract<keyof NonFunctionProperties<ObjectT>, string | number>;
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+export type MaskTree = {
+    [key: string]: MaskTree | MarkedSymbolType;
+};
+export interface IMask<ObjectT, FieldTupleT extends readonly MaskAnyTerm<ObjectT>[]> {
+    toObject: () => MaskTree;
+}
+export type MaskBuilderFunc<ItemT, FieldTupleT extends readonly any[]> = (provider: MaskProvider<ItemT>) => FieldTupleT;
+export declare class MaskPlainTerm<ObjectT, KeyT extends ValidKeys<ObjectT>> {
+    readonly key: KeyT;
+    constructor(key: KeyT);
+}
+export declare class MaskCompositeTerm<ObjectT, KeyT extends ValidKeys<ObjectT>, ItemT> {
+    readonly key: KeyT;
+    constructor(key: KeyT);
+    mask<FieldTupleT extends readonly any[]>(builderFn: MaskBuilderFunc<ItemT, FieldTupleT>): MaskCompiledTerm<ObjectT, KeyT, MaskDef<ItemT, FieldTupleT>>;
+}
+export type MaskProvider<ObjectT> = {
+    [KeyT in ValidKeys<ObjectT>]: ObjectT[KeyT] extends readonly (infer ItemT)[] ? MaskCompositeTerm<ObjectT, KeyT, ItemT> : ObjectT[KeyT] extends object ? MaskCompositeTerm<ObjectT, KeyT, ObjectT[KeyT]> : MaskPlainTerm<ObjectT, KeyT>;
+};
+export declare class MaskDef<ObjectT, FieldTupleT extends readonly MaskAnyTerm<ObjectT>[]> {
+}
+export declare class MaskCompiledTerm<ObjectT, KeyT extends ValidKeys<ObjectT>, MaskDefT extends MaskDef<ObjectT[KeyT], any>> {
+    readonly key: KeyT;
+    constructor(key: KeyT);
+}
+export type MaskAnyTerm<ObjectT> = MaskPlainTerm<ObjectT, any> | MaskCompositeTerm<ObjectT, any, any> | MaskCompiledTerm<ObjectT, any, any>;
+export type MaskDefInfer<T> = T extends MaskDef<infer ObjectT, infer FieldTupleT> ? FieldTupleT extends readonly MaskAnyTerm<ObjectT>[] ? Prettify<FieldsTupleToObject<ObjectT, FieldTupleT>> : never : never;
+type MaskAnyTermToObject<TermT extends MaskAnyTerm<any>> = TermT extends MaskPlainTerm<infer ObjectT, infer KeyT> | MaskCompositeTerm<infer ObjectT, infer KeyT, any> ? {
+    [K in KeyT]: ObjectT[K];
+} : TermT extends MaskCompiledTerm<infer ObjectT, infer KeyT, infer MaskDefT> ? ObjectT[KeyT] extends readonly any[] ? {
+    [K in KeyT]: MaskDefInfer<MaskDefT>[];
+} : {
+    [K in KeyT]: MaskDefInfer<MaskDefT>;
+} : never;
+type FieldsTupleToObject<ObjectT, TupleT extends readonly MaskAnyTerm<ObjectT>[]> = UnionToIntersection<MaskAnyTermToObject<TupleT[number]>>;
+export type MaskInfer<T> = T extends IMask<infer ObjectT, infer FieldTupleT> ? MaskDefInfer<MaskDef<ObjectT, FieldTupleT>> : never;
+export {};

package/dist/types.js

@@ -0,0 +1,20 @@
+export class MaskPlainTerm {
+    constructor(key) {
+        this.key = key;
+    }
+}
+export class MaskCompositeTerm {
+    constructor(key) {
+        this.key = key;
+    }
+    mask(builderFn) {
+        return null;
+    }
+}
+export class MaskDef {
+}
+export class MaskCompiledTerm {
+    constructor(key) {
+        this.key = key;
+    }
+}

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAsCA,MAAa,aAAa;IACI;IAA5B,YAA4B,GAAS;QAAT,QAAG,GAAH,GAAG,CAAM;IAAG,CAAC;CAC1C;AAFD,sCAEC;AAED,MAAa,iBAAiB;IAKA;IAA5B,YAA4B,GAAS;QAAT,QAAG,GAAH,GAAG,CAAM;IAAG,CAAC;IAEzC,IAAI,CACF,SAA8C;QAE9C,OAAO,IAAW,CAAC;IACrB,CAAC;CACF;AAZD,8CAYC;AAUD,MAAa,OAAO;CAGhB;AAHJ,0BAGI;AAEJ,MAAa,gBAAgB;IAKC;IAA5B,YAA4B,GAAS;QAAT,QAAG,GAAH,GAAG,CAAM;IAAG,CAAC;CAC1C;AAND,4CAMC"}

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+import { MaskBuilderFunc, IMask } from "./types.js";
+export declare function createMask<ObjectT, FieldTupleT extends readonly any[]>(maskBuilderFn: MaskBuilderFunc<ObjectT, FieldTupleT>): IMask<ObjectT, FieldTupleT>;

package/dist/utils.js

@@ -0,0 +1,41 @@
+import { MarkedSymbol } from "./constants.js";
+class MaskBranch {
+    constructor(key, subtree) {
+        this.key = key;
+        this.subtree = subtree;
+    }
+}
+export function createMask(maskBuilderFn) {
+    const proxy = createMaskProxy();
+    // Trick: public types are designed to trick the user and make inference work
+    const pickedTerms = maskBuilderFn(proxy);
+    const branchSubtree = compileBranchSubtree(pickedTerms);
+    return {
+        toObject() {
+            return branchSubtree;
+        },
+    };
+}
+function compileBranchSubtree(pickedTerms) {
+    const subtree = {};
+    for (const field of pickedTerms) {
+        subtree[field.key] =
+            field instanceof MaskBranch ? field.subtree : MarkedSymbol;
+    }
+    return subtree;
+}
+function createMaskProxy() {
+    return new Proxy(new Object(), {
+        get(_, propName) {
+            return {
+                key: propName,
+                mask: (maskBuilderFn) => {
+                    const proxy = createMaskProxy();
+                    const pickedTerms = maskBuilderFn(proxy);
+                    const branchSubtree = compileBranchSubtree(pickedTerms);
+                    return new MaskBranch(propName, branchSubtree);
+                },
+            };
+        },
+    });
+}

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";;AAiBA,gCAiBC;AAlCD,2CAA2C;AAU3C,MAAM,UAAU;IAEL;IACA;IAFT,YACS,GAAoB,EACpB,OAAiB;QADjB,QAAG,GAAH,GAAG,CAAiB;QACpB,YAAO,GAAP,OAAO,CAAU;IACvB,CAAC;CACL;AAED,SAAgB,UAAU,CACxB,aAAoD;IAEpD,MAAM,KAAK,GAAG,eAAe,EAAW,CAAC;IAEzC,6EAA6E;IAC7E,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAEtC,CAAC;IAEF,MAAM,aAAa,GAAG,oBAAoB,CAAC,WAAkB,CAAC,CAAC;IAE/D,OAAO;QACL,QAAQ;YACN,OAAO,aAAa,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,WAA0C;IACtE,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;YAChB,KAAK,YAAY,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAY,CAAC;IAC/D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,eAAe;IACtB,OAAO,IAAI,KAAK,CAAC,IAAI,MAAM,EAAE,EAAE;QAC7B,GAAG,CAAC,CAAC,EAAE,QAAgB;YACrB,OAAO;gBACL,GAAG,EAAE,QAAQ;gBACb,IAAI,EAAE,CAAC,aAAwC,EAAE,EAAE;oBACjD,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;oBAChC,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;oBACzC,MAAM,aAAa,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;oBAExD,OAAO,IAAI,UAAU,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;gBACjD,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAA0B,CAAC;AAC9B,CAAC"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@so0shka/ts-mask",
+  "version": "1.0.0",
+  "description": "A TypeScript library for creating object field masks and inferring types from them",
+  "homepage": "https://github.com/So0shka/ts-mask#readme",
+  "bugs": {
+    "url": "https://github.com/So0shka/ts-mask/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/So0shka/ts-mask.git"
+  },
+  "license": "MIT",
+  "author": "So0shka",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}