refactor: refactor tinyShield into publishable library workspace (#74)

* feat: Implement Ad-Shield domain filtering and wildcard handling

- Add SafeArrayToString utility for safe array string conversion.
- Introduce custom-defined matches and exclusion sets for domain filtering.
- Create functions to fetch Ad-Shield domains from AdGuard and uBlock Origin filter lists.
- Implement logic to parse and filter Ad-Shield domains, including CDN checks.
- Add IAB sellers fetching functionality with validation.
- Develop utility functions for domain wildcard handling and grouping by TLD.
- Enhance testing suite with comprehensive tests for new functionalities.
- Update TypeScript configuration for libraries and userscript.
- Modify package.json scripts for improved build processes and workspace management.

* chore: Add license and keywords to package.json for better package metadata

Author: piquark6046

.github/workflows/npm.yml

@@ -1,10 +1,10 @@
-name: 'Publish to npm'
+name: "Publish to npm"
 on:
   release:
     types: [published]
   push:
     tags:
-      - '*.*.*-build.*'
+      - "*.*.*-build.*"
 
 jobs:
   release:
@@ -17,8 +17,8 @@ jobs:
       - name: Set up NodeJS LTS
         uses: actions/setup-node@v6
         with:
-          node-version: 'lts/*'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "lts/*"
+          registry-url: "https://registry.npmjs.org"
       - name: Update npm package manager
         run: npm install -g npm@latest
       - name: Checkout
@@ -29,11 +29,17 @@ jobs:
         run: mkdir -p ~/.pnpm-store && pnpm config set store-dir ~/.pnpm-store
       - name: Install dependencies
         run: pnpm install --no-lockfile
-      - name: Bump package.json version from tag
+      - name: Bump @filteringdev/tinyshield package.json version from tag
         uses: TypescriptPrime/bump-packagejson-version@72720c4d073ed0c5b9e9393d7334abfe3fabb47c
+      - name: Bump @filteringdev/tinyshield-lib package.json version from tag
+        run: npm pkg set version="${GITHUB_REF_NAME#v}" -w libs
       - name: Build
         run: npm run build
-      - name : Publish to npm
+      - name: Publish @filteringdev/tinyshield to npm
+        working-directory: .
+        run: npm publish --access public
+      - name: Publish @filteringdev/tinyshield-lib to npm
+        working-directory: libs
         run: npm publish --access public
     if: ${{ github.event_name == 'release' && github.event.release.prerelease == false }}
   beta-release:
@@ -46,8 +52,8 @@ jobs:
       - name: Set up NodeJS LTS
         uses: actions/setup-node@v6
         with:
-          node-version: 'lts/*'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "lts/*"
+          registry-url: "https://registry.npmjs.org"
       - name: Update npm package manager
         run: npm install -g npm@latest
       - name: Checkout
@@ -58,11 +64,17 @@ jobs:
         run: mkdir -p ~/.pnpm-store && pnpm config set store-dir ~/.pnpm-store
       - name: Install dependencies
         run: pnpm install --no-lockfile
-      - name: Bump package.json version from tag
+      - name: Bump @filteringdev/tinyshield package.json version from tag
         uses: TypescriptPrime/bump-packagejson-version@72720c4d073ed0c5b9e9393d7334abfe3fabb47c
+      - name: Bump @filteringdev/tinyshield-lib package.json version from tag
+        run: npm pkg set version="${GITHUB_REF_NAME#v}" -w libs
       - name: Build
         run: npm run build
-      - name : Publish to npm
+      - name: Publish @filteringdev/tinyshield to npm
+        working-directory: .
+        run: npm publish --tag beta --access public
+      - name: Publish @filteringdev/tinyshield-lib to npm
+        working-directory: libs
         run: npm publish --tag beta --access public
     if: ${{ github.event_name == 'release' && github.event.release.prerelease == true && contains(github.event.release.tag_name, '-beta.') }}
   build-release:
@@ -75,8 +87,8 @@ jobs:
       - name: Set up NodeJS LTS
         uses: actions/setup-node@v6
         with:
-          node-version: 'lts/*'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "lts/*"
+          registry-url: "https://registry.npmjs.org"
       - name: Update npm package manager
         run: npm install -g npm@latest
       - name: Checkout
@@ -87,11 +99,17 @@ jobs:
         run: mkdir -p ~/.pnpm-store && pnpm config set store-dir ~/.pnpm-store
       - name: Install dependencies
         run: pnpm install --no-lockfile
-      - name: Bump package.json version from tag
+      - name: Bump @filteringdev/tinyshield package.json version from tag
         uses: TypescriptPrime/bump-packagejson-version@72720c4d073ed0c5b9e9393d7334abfe3fabb47c
+      - name: Bump @filteringdev/tinyshield-lib package.json version from tag
+        run: npm pkg set version="${GITHUB_REF_NAME#v}" -w libs
       - name: Build
         run: npm run build
-      - name : Publish to npm
+      - name: Publish @filteringdev/tinyshield to npm
+        working-directory: .
+        run: npm publish --tag build --access public
+      - name: Publish @filteringdev/tinyshield-lib to npm
+        working-directory: libs
         run: npm publish --tag build --access public
     if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') && contains(github.ref, '-build.') }}
   purge:
@@ -104,10 +122,10 @@ jobs:
       - name: Set up NodeJS LTS
         uses: actions/setup-node@v6
         with:
-          node-version: 'lts/*'
+          node-version: "lts/*"
       - name: Purge jsdelivr cache
         uses: FilteringDev/jsdelivr-purge-npm@0bee790e911f359243cd8d98cd87f6bbbc879e80
         with:
-          package: '@filteringdev/tinyshield'
-          disttag: 'latest'
-    needs: [release]
+          package: "@filteringdev/tinyshield"
+          disttag: "latest"
+    needs: [release]

builder/package.json

@@ -6,11 +6,12 @@
     "lint": "tsc --noEmit && eslint **/*.ts",
     "build": "tsx source/buildci.ts",
     "debug": "tsx source/debug.ts",
-    "test": "npm run test:utils",
-    "test:utils": "ava test/utils/**/*.test.ts"
+    "test": "echo \"Builder tests moved to @filteringdev/tinyshield-lib.\"",
+    "test:utils": "echo \"Builder utility tests moved to @filteringdev/tinyshield-lib.\""
   },
   "dependencies": {
-    "@types/node": "^24.12.2"
+    "@types/node": "^24.12.2",
+    "@filteringdev/tinyshield-lib": "workspace:*"
   },
   "ava": {
     "files": [
@@ -28,20 +29,15 @@
     }
   },
   "devDependencies": {
-    "@adguard/agtree": "^4.1.1",
-    "@ava/typescript": "^7.0.0",
     "@npmcli/package-json": "^8.0.0",
     "@types/npmcli__package-json": "^4.0.4",
     "@typescript-eslint/eslint-plugin": "^8.59.2",
     "@typescript-eslint/parser": "^8.59.2",
     "@typescriptprime/parsing": "^2.0.1",
-    "@typescriptprime/securereq": "^2.0.0",
-    "ava": "^8.0.0",
     "chokidar": "^5.0.0",
     "esbuild": "^0.28.0",
     "eslint": "^10.3.0",
     "piscina": "^5.1.4",
-    "tldts": "^7.0.30",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.2",

builder/source/build-core.ts

@@ -1,6 +1,6 @@
 import * as Zod from 'zod'
 import * as Process from 'node:process'
-import { FetchAdShieldDomains, type TASDomainContainer } from './references/index.js'
+import { FetchAdShieldDomains, type TASDomainContainer } from '@filteringdev/tinyshield-lib/references'
 import { SafeInitCwd } from './utils/safe-init-cwd.js'
 
 export type BuildOptions = {

builder/source/debug.ts

@@ -9,7 +9,7 @@ import { Build } from './build-core.js'
 
 let ProjectRoot = SafeInitCwd({ Cwd: Process.cwd(), InitCwd: Process.env.INIT_CWD })
 const WatchingGlob: string[] = []
-for (const Dir of ['builder/', 'userscript/', '']) {
+for (const Dir of ['builder/', 'userscript/', 'libs/', '']) {
   WatchingGlob.push(...Fs.globSync(`${ProjectRoot}/${Dir}source/**/*.ts`))
   WatchingGlob.push(...Fs.globSync(`${ProjectRoot}/${Dir}source/**/*.json`))
   WatchingGlob.push(...Fs.globSync(`${ProjectRoot}/${Dir}source/**/*.txt`))

libs/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@filteringdev/tinyshield-lib",
+  "version": "0.0.0",
+  "description": "Library APIs for tinyShield userscript monkey patches and reference domain loading.",
+  "type": "module",
+  "files": [
+    "dist/**/*"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./monkey-patches": {
+      "types": "./dist/monkey-patches/index.d.ts",
+      "import": "./dist/monkey-patches/index.js"
+    },
+    "./references": {
+      "types": "./dist/references/index.d.ts",
+      "import": "./dist/references/index.js"
+    }
+  },
+  "license": "MPL-2.0",
+  "keywords": [
+    "Ad-Shield"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FilteringDev/tinyShield.git"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc --noEmit && eslint source/**/*.ts test/**/*.ts",
+    "test": "npm run build && ava test/**/*.test.ts"
+  },
+  "dependencies": {
+    "@adguard/agtree": "^4.1.1",
+    "@typescriptprime/securereq": "^2.0.0",
+    "tldts": "^7.0.30",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@ava/typescript": "^7.0.0",
+    "@types/node": "^24.12.2",
+    "@types/web": "^0.0.349",
+    "@typescript-eslint/eslint-plugin": "^8.59.2",
+    "@typescript-eslint/parser": "^8.59.2",
+    "ava": "^8.0.0",
+    "eslint": "^10.3.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.2"
+  },
+  "ava": {
+    "files": [
+      "test/**/*.test.ts"
+    ],
+    "nodeArguments": [
+      "--import=tsx"
+    ],
+    "workerThreads": false,
+    "typescript": {
+      "compile": false,
+      "rewritePaths": {
+        "source/": "dist/"
+      }
+    }
+  }
+}

libs/source/index.ts

@@ -0,0 +1,10 @@
+export {
+  CreateTinyShieldController,
+  EnableTinyShield,
+  TinyShieldPatchIds,
+  type TinyShieldController,
+  type TinyShieldControllerOptions,
+  type TinyShieldPatchController,
+  type TinyShieldPatchId,
+  type TinyShieldWindow
+} from './monkey-patches/index.js'

userscript/source/as-weakmap.ts libs/source/monkey-patches/as-weakmap.tsuserscript/source/as-weakmap.ts renamed to libs/source/monkey-patches/as-weakmap.ts

@@ -8,16 +8,18 @@
  *   - See Git history at https://github.com/FilteringDev/tinyShield for detailed authorship information.
  */
 
-import { OriginalRegExpTest } from './index.js'
-
-type CheckDepthResult = { Status: 'matched' } | { Status: 'not-matched' } | { Status: 'too-expensive' } | { Status: 'unsafe-object'; Reason: unknown }
-
-type CheckBudget = {
-  MaxTopLevelKeys: number;
-  MaxArrayItems: number;
-  MaxInnerKeysPerObject: number;
-  MaxOperations: number;
-};
+export type CheckDepthResult =
+  { Status: 'matched' } |
+  { Status: 'not-matched' } |
+  { Status: 'too-expensive' } |
+  { Status: 'unsafe-object'; Reason: unknown }
+
+export type CheckBudget = {
+  MaxTopLevelKeys: number
+  MaxArrayItems: number
+  MaxInnerKeysPerObject: number
+  MaxOperations: number
+}
 
 const DefaultBudget: CheckBudget = {
   MaxTopLevelKeys: 300,
@@ -48,6 +50,7 @@ function CountCommonKnownKeys(Obj: object): number {
 export function CheckDepthInASWeakMapBudgeted(
   Args: [object, unknown],
   Budget: CheckBudget = DefaultBudget,
+  OriginalRegExpTest: typeof RegExp.prototype.test = RegExp.prototype.test,
 ): CheckDepthResult {
   let Operations = 0
 
@@ -133,7 +136,7 @@ export function CheckDepthInASWeakMapBudgeted(
     }
 
     return { Status: 'not-matched' }
-  } catch (error) {
-    return { Status: 'unsafe-object', Reason: error }
+  } catch (Error) {
+    return { Status: 'unsafe-object', Reason: Error }
   }
-}
+}