fix(docs): refresh project guidance for TC39 decorators, build configuration, and dependency compatibility

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2026-03-24 - 7.1.2 - fix(docs)
+refresh project guidance for TC39 decorators, build configuration, and dependency compatibility
+
+- streamlines readme hints to focus on current decorator patterns and runtime support
+- adds compatibility notes for the updated build toolchain and dependency APIs
+- includes the project license file in the repository
+
 ## 2026-03-24 - 7.1.1 - fix(build)
 update build and test tooling configuration, migrate project config to .smartconfig.json, and align TypeScript typings
 

license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Task Venture Capital GmbH
+
+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.

readme.hints.md

@@ -1,113 +1,29 @@
 # Project Memory - Smartdata
 
-## TC39 Decorator Migration (v6.0.0) - ✅ COMPLETED
+## TC39 Decorator Pattern
-
-### Final Status: All Tests Passing (157/157)
-
-Migration successfully completed on 2025-11-17.
-
-### What Changed:
-
-- ✅ Removed `experimentalDecorators` from tsconfig.json
-- ✅ Refactored all 7 decorators to TC39 Stage 3 syntax
-  - 5 property decorators: @globalSvDb, @svDb, @unI, @index, @searchable
-  - 2 class decorators: @Collection, @managed
-- ✅ Implemented context.metadata pattern for shared decorator state
-- ✅ All tests passing across Node.js and Deno runtimes
-
-### Critical Discovery: TC39 Metadata Access Pattern
-
-**THE KEY INSIGHT**: In TC39 decorators, metadata is NOT accessed via `constructor[Symbol.metadata]`. Instead:
 
 - **Field decorators**: Write to `context.metadata`
-- **Class decorators**: Read from `context.metadata` (same shared object!)
+- **Class decorators**: Read from `context.metadata` (same shared object)
-- The `context.metadata` object is shared between all decorators on the same class
+- `Symbol.metadata` on constructors is read-only (managed by runtime)
-- Attempting to write to `constructor[Symbol.metadata]` throws: "Cannot assign to read only property"
+- Field decorators run before class decorators (guaranteed order)
+- `declare` keyword for instance properties accessed via prototype getters (avoids ES2022 shadowing)
 
-### Implementation Pattern:
+### Runtime Compatibility
 
-```typescript
+- ✅ Node.js v20+ / v25+: Full TC39 support
-// Field decorator - stores metadata
+- ✅ Deno v2.x: Full TC39 support
-export function svDb() {
+- ❌ Bun: No TC39 support (uses legacy decorators only)
-  return (value: undefined, context: ClassFieldDecoratorContext) => {
-    const metadata = context.metadata as ISmartdataDecoratorMetadata;
-    if (!metadata.saveableProperties) {
-      metadata.saveableProperties = [];
-    }
-    metadata.saveableProperties.push(String(context.name));
-  };
-}
 
-// Class decorator - reads metadata and initializes prototype
+## Build Configuration (v7.1.0+)
-export function Collection(dbArg: SmartdataDb) {
-  return function(value: Function, context: ClassDecoratorContext) => {
-    const metadata = context.metadata as ISmartdataDecoratorMetadata;
-    if (metadata?.saveableProperties) {
-      decoratedClass.prototype.saveableProperties = [...metadata.saveableProperties];
-    }
-    return decoratedClass;
-  };
-}
-```
 
-### Runtime Compatibility:
+- **Build tool**: `@git.zone/tsbuild` v4 with `tsbuild tsfolders`
+- **tsconfig.json**: Includes `"types": ["node"]` since tsbuild v4 defaults to DOM+ESNext lib only
+- **Strict mode**: tsbuild v4 enables strict checks; properties use `!` definite assignment or `declare`
+- **Test imports**: Use `@git.zone/tstest/tapbundle` (NOT `@push.rocks/tapbundle`)
+- **Config file**: `.smartconfig.json` (renamed from `npmextra.json`)
 
-- ✅ **Node.js v23.8.0**: Full TC39 support
+## Dependencies (v7.1.0+)
-- ✅ **Deno v2.5.4**: Full TC39 support
-- ❌ **Bun v1.3.0**: No TC39 support (uses legacy decorators only)
-  - Removed "+bun" from test filenames to skip Bun tests
 
-### Key Technical Notes:
+- `@push.rocks/taskbuffer` v8: distributedCoordination API at `taskbuffer.distributedCoordination.*`
-
+- `@push.rocks/smartmongo` v5: API compatible (`createAndStart`, `getMongoDescriptor`, `stop`, `stopAndDumpToDir`)
-1. **Metadata Initialization Timing**: Class decorators run AFTER field decorators, allowing them to read accumulated metadata and initialize prototypes before any instances are created
+- `mongodb` v7.1: ChangeStream requires `Document` constraint, use `any` for generic watcher
-2. **Prototype vs Instance Properties**: Properties set on prototype are accessible via `this.propertyName` in instances
-3. **TypeScript Lib Support**: TypeScript 5.9.3 includes built-in decorator types (no custom lib configuration needed)
-4. **Interface Naming**: Used `ISmartdataDecoratorMetadata` extending `DecoratorMetadataObject` for type safety
-
-### Files Modified:
-
-- ts/classes.doc.ts (property decorators + metadata interface)
-- ts/classes.collection.ts (class decorators + prototype initialization)
-- tsconfig.json (removed experimentalDecorators flag)
-- test/\*.ts (renamed files to remove "+bun" suffix)
-
-### Test Results:
-
-All 157 tests passing across 10 test files:
-
-- test.cursor.ts: 7/7
-- test.deno.ts: 11/11 (queries working correctly!)
-- test.search.advanced.ts: 41/41
-- test.typescript.ts: 4/4
-- test.watch.ts: 5/5
-- And 5 more test files
-
-### Migration Learnings for Future Reference:
-
-1. `context.metadata` is the ONLY way to share state between decorators
-2. Class decorators must initialize prototypes from metadata immediately
-3. `Symbol.metadata` on constructors is read-only (managed by runtime)
-4. Field decorators run before class decorators (guaranteed order)
-5. TypeScript 5.2+ has built-in TC39 decorator support
-
-## ES2022 Class Fields & Prototype Getters - Fixed in v7.0.15
-
-### Issue
-
-ES2022 class fields (`useDefineForClassFields: true`) create own properties during construction that shadow prototype getters defined by decorators.
-
-### Solution
-
-Use `declare` keyword for instance properties that are accessed via prototype getters:
-
-```typescript
-// In SmartDataDbDoc (ts/classes.doc.ts):
-declare public collection: SmartdataCollection<any>;  // Type-only, no JS emitted
-declare public manager: TManager;  // Type-only, no JS emitted
-```
-
-### Key Insight
-
-- `declare` tells TypeScript this is a type-only declaration
-- No JavaScript code is emitted for `declare` properties
-- Prototype getters defined by `@Collection` and `@managed` decorators are no longer shadowed

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdata',
-  version: '7.1.1',
+  version: '7.1.2',
   description: 'An advanced library for NoSQL data organization and manipulation using TypeScript with support for MongoDB, data validation, collections, and custom data types.'
 }