@decaf-ts/for-fabric 0.0.2

package/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Tiago Venceslau and Contributors
+
+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,647 @@
+[![Banner](./workdocs/assets/Banner.png)](https://decaf-ts.github.io/ts-workspace/)
+## Hyperledger Fabric Contracts for DECAF
+
+Chaincode-side building blocks for Hyperledger Fabric written in TypeScript. This module provides repositories, CRUD contracts (object and serialized JSON), an ERC20 sample contract, Fabric-backed sequences, event emission, and context-aware logging. It adapts DECAF’s data-access patterns to Fabric’s world-state so you can write smart contracts with the same Repository/Model abstractions used elsewhere in DECAF.
+
+
+![Licence](https://img.shields.io/github/license/decaf-ts/for-fabric.svg?style=plastic)
+![GitHub language count](https://img.shields.io/github/languages/count/decaf-ts/for-fabric?style=plastic)
+![GitHub top language](https://img.shields.io/github/languages/top/decaf-ts/for-fabric?style=plastic)
+
+[![Build & Test](https://github.com/decaf-ts/for-fabric/actions/workflows/nodejs-build-prod.yaml/badge.svg)](https://github.com/decaf-ts/for-fabric/actions/workflows/nodejs-build-prod.yaml)
+[![CodeQL](https://github.com/decaf-ts/for-fabric/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/decaf-ts/for-fabric/actions/workflows/codeql-analysis.yml)[![Snyk Analysis](https://github.com/decaf-ts/for-fabric/actions/workflows/snyk-analysis.yaml/badge.svg)](https://github.com/decaf-ts/for-fabric/actions/workflows/snyk-analysis.yaml)
+[![Pages builder](https://github.com/decaf-ts/for-fabric/actions/workflows/pages.yaml/badge.svg)](https://github.com/decaf-ts/for-fabric/actions/workflows/pages.yaml)
+[![.github/workflows/release-on-tag.yaml](https://github.com/decaf-ts/for-fabric/actions/workflows/release-on-tag.yaml/badge.svg?event=release)](https://github.com/decaf-ts/for-fabric/actions/workflows/release-on-tag.yaml)
+
+![Open Issues](https://img.shields.io/github/issues/decaf-ts/for-fabric.svg)
+![Closed Issues](https://img.shields.io/github/issues-closed/decaf-ts/for-fabric.svg)
+![Pull Requests](https://img.shields.io/github/issues-pr-closed/decaf-ts/for-fabric.svg)
+![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)
+
+![Forks](https://img.shields.io/github/forks/decaf-ts/for-fabric.svg)
+![Stars](https://img.shields.io/github/stars/decaf-ts/for-fabric.svg)
+![Watchers](https://img.shields.io/github/watchers/decaf-ts/for-fabric.svg)
+
+![Node Version](https://img.shields.io/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbadges%2Fshields%2Fmaster%2Fpackage.json&label=Node&query=$.engines.node&colorB=blue)
+![NPM Version](https://img.shields.io/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbadges%2Fshields%2Fmaster%2Fpackage.json&label=NPM&query=$.engines.npm&colorB=purple)
+
+Documentation available [here](https://decaf-ts.github.io/for-fabric/)
+
+### Description
+
+This module focuses on the chaincode (contracts) side of @decaf-ts/for-fabric. It adapts DECAF’s Repository/Model/Adapter abstractions to Hyperledger Fabric’s world state and execution context so you can implement smart contracts with familiar patterns and minimal boilerplate.
+
+Key ideas:
+- Keep your domain models as annotated classes (using @decaf-ts/decorator-validation).
+- Use a Repository to persist/read/query models through a Fabric-aware Adapter.
+- Compose reusable CRUD contracts and utilities instead of hand-writing stub calls.
+- Emit first-class Fabric events from repository operations.
+- Leverage context-aware logging and typed flags during execution.
+
+Contracts building blocks identified in src/contracts:
+
+1) Core context and types
+- FabricContractContext: Extends the generic Context to expose Fabric-specific properties (stub, clientIdentity, logger) and timestamp resolution from the ledger.
+- FabricContractFlags: Interface extending RepositoryFlags with stub, clientIdentity and logger for contract calls.
+
+2) Logging
+- ContractLogger: MiniLogger-compatible logger bound to the Fabric contract Context. It honors log levels and forwards to the underlying Fabric logger.
+
+3) Adapter and repository
+- FabricContractAdapter: Chaincode-side Adapter that implements CRUD, bulk operations, raw Mango queries, result iteration, model preparation/reversion, composite-key prefixes, and sequence creation. Bridges DECAF abstractions to Fabric (ChaincodeStub, ClientIdentity) and CouchDB-style queries.
+- FabricContractRepository<M>: Repository for models inside chaincode. Supports create, update, createAll, updateAll, read/readAll, raw queries (Mango), select projections, prefix-based bulk ops, and event emission through an ObserverHandler.
+- FabricContractRepositoryObservableHandler: ObserverHandler that emits Fabric events via stub.setEvent using names generated by generateFabricEventName.
+
+4) Sequences
+- FabricContractDBSequence: Fabric-backed implementation of Sequence with current, next and range. Stores values in the world state via FabricContractRepository and supports Number or BigInt sequences with configurable startWith and incrementBy.
+
+5) CRUD contracts
+- FabricCrudContract<M>: Base smart contract exposing CRUD endpoints (create, read, update, delete, createAll, readAll, updateAll, deleteAll, raw, init, healthcheck) for a model type. Uses DeterministicSerializer and the FabricContractAdapter/Repository behind the scenes and provides logFor(ctx).
+- SerializedCrudContract<M>: Same endpoints as FabricCrudContract but takes/returns JSON strings (de)serialized to the model class. This simplifies client interactions and is used in tests.
+
+6) ERC20 sample
+- ERC20Token, ERC20Wallet, Allowance: Sample domain models for an ERC20-like token, wallets and allowances.
+- FabricStatement<M,R>: A CouchDBStatement bridge that runs Mango queries through FabricContractAdapter, handling primary key projection when needed.
+- FabricERC20Contract: A full ERC20 smart contract showcasing repository-based persistence and arithmetic helpers. Implements Initialize, CheckInitialized, TokenName, Symbol, Decimals, TotalSupply, BalanceOf, Transfer, TransferFrom, Approve, Allowance, Mint, Burn, BurnFrom, ClientAccountBalance, ClientAccountID and an internal _transfer helper.
+
+Design notes:
+- Deterministic serialization is used to ensure stable bytes for world-state writes.
+- onCreate/onCreateUpdate hooks from db-decorators are leveraged by the adapter to set primary keys and creator/owner metadata.
+- Mango queries (CouchDB) are used for rich queries via getQueryResultWithPagination.
+- Event emission is opt-in per operation type through FabricContractRepositoryObservableHandler’s supportedEvents list.
+
+With these components you can build robust chaincode while keeping code concise, testable, and aligned with DECAF’s architecture.
+
+
+### How to Use
+
+## Installation
+
+```bash
+npm install @decaf-ts/for-fabric
+```
+
+## Client-Side Usage
+
+### Connecting to a Fabric Network
+
+```typescript
+import { FabricAdapter, PeerConfig } from '@decaf-ts/for-fabric';
+
+// Configure connection to a Fabric peer
+const config: PeerConfig = {
+  mspId: 'Org1MSP',
+  peerEndpoint: 'localhost:7051',
+  channelName: 'mychannel',
+  chaincodeName: 'mycc',
+  contractName: 'mycontract',
+  tlsCertPath: '/path/to/tls/cert',
+  certDirectoryPath: '/path/to/cert/dir',
+  keyDirectoryPath: '/path/to/key/dir',
+  cryptoPath: '/path/to/crypto',
+  peerHostAlias: 'peer0.org1.example.com',
+  caEndpoint: 'localhost:7054',
+  caTlsCertificate: '/path/to/ca/tls/cert',
+  caCert: '/path/to/ca/cert',
+  caKey: '/path/to/ca/key',
+  ca: 'ca.org1.example.com'
+};
+
+// Create an adapter instance
+const adapter = new FabricAdapter(config, 'org1-adapter');
+
+// Use the adapter to interact with the Fabric network
+async function createAsset() {
+  const asset = { id: 'asset1', value: 'Asset 1 Value' };
+  return await adapter.create('assets', 'asset1', asset, {}, mySerializer);
+}
+
+async function readAsset(id: string) {
+  return await adapter.read('assets', id, mySerializer);
+}
+
+async function updateAsset(id: string, newValue: string) {
+  const asset = await readAsset(id);
+  asset.value = newValue;
+  return await adapter.update('assets', id, asset, {}, mySerializer);
+}
+
+async function deleteAsset(id: string) {
+  return await adapter.delete('assets', id, mySerializer);
+}
+
+async function queryAssets(owner: string) {
+  const query = {
+    selector: {
+      owner: owner
+    }
+  };
+  return await adapter.raw(query, true);
+}
+```
+
+### Listening for Chaincode Events
+
+```typescript
+import { FabricAdapter, FabricDispatch } from '@decaf-ts/for-fabric';
+
+async function setupEventListener(config: PeerConfig) {
+  // Create a client
+  const client = await FabricAdapter.getClient(config);
+
+  // Create a dispatch instance
+  const dispatch = new FabricDispatch(client);
+
+  // Configure the dispatch with peer configuration
+  dispatch.configure(config);
+
+  // Register an observer for a specific table and event
+  dispatch.observe('assets', 'create', (id) => {
+    console.log(`Asset created: ${id}`);
+    // Fetch the new asset or update UI
+  });
+
+  // Start listening for events
+  await dispatch.start();
+
+  // When done, close the connection
+  // await dispatch.close();
+}
+```
+
+### Working with Identities and Certificates
+
+```typescript
+import { 
+  getIdentity, 
+  getSigner, 
+  readFile, 
+  getCAUser 
+} from '@decaf-ts/for-fabric';
+
+async function setupIdentity() {
+  // Read a certificate file
+  const tlsCert = await readFile('/path/to/tls/cert');
+
+  // Get an identity from a certificate directory
+  const identity = await getIdentity('Org1MSP', '/path/to/cert/dir');
+
+  // Get a signer from a key directory
+  const signer = await getSigner('/path/to/key/dir');
+
+  // Create a CA user
+  const user = await getCAUser(
+    'user1', 
+    privateKeyPem, 
+    certificatePem, 
+    'Org1MSP'
+  );
+
+  return { identity, signer, user };
+}
+```
+
+## Chaincode Development
+
+### Creating a Model
+
+```typescript
+import { Model, id, property, table } from '@decaf-ts/decorator-validation';
+
+@table('assets')
+export class Asset extends Model {
+  @id()
+  id: string;
+
+  @property()
+  value: string;
+
+  @property()
+  owner: string;
+
+  @property()
+  createdAt: number;
+}
+```
+
+### Creating a CRUD Contract
+
+```typescript
+import { FabricCrudContract } from '@decaf-ts/for-fabric';
+import { Context, Contract, Info, Transaction } from 'fabric-contract-api';
+import { Asset } from './asset';
+
+@Info({ title: 'AssetContract', description: 'Smart contract for trading assets' })
+export class AssetContract extends FabricCrudContract<Asset> {
+  constructor() {
+    super('AssetContract', Asset);
+  }
+
+  // The base class already provides standard CRUD operations:
+  // create, read, update, delete, createAll, readAll, updateAll, deleteAll
+
+  // Add custom methods as needed
+  @Transaction()
+  async getAssetHistory(ctx: Context, id: string): Promise<any[]> {
+    const stub = ctx.stub;
+    const iterator = await stub.getHistoryForKey(id);
+
+    const results = [];
+    let result = await iterator.next();
+
+    while (!result.done) {
+      const value = result.value;
+      results.push({
+        txId: value.txId,
+        timestamp: value.timestamp,
+        value: JSON.parse(value.value.toString('utf8'))
+      });
+
+      result = await iterator.next();
+    }
+
+    await iterator.close();
+    return results;
+  }
+
+  @Transaction()
+  async transferAsset(ctx: Context, id: string, newOwner: string): Promise<Asset> {
+    const asset = await this.read(ctx, id);
+    asset.owner = newOwner;
+    return await this.update(ctx, asset);
+  }
+}
+```
+
+### Using the Contract Adapter Directly
+
+```typescript
+import { FabricContractAdapter } from '@decaf-ts/for-fabric';
+import { Context, Contract, Transaction } from 'fabric-contract-api';
+
+export class CustomContract extends Contract {
+  private adapter: FabricContractAdapter;
+
+  constructor() {
+    super('CustomContract');
+    this.adapter = new FabricContractAdapter();
+  }
+
+  @Transaction()
+  async createRecord(ctx: Context, id: string, data: string): Promise<any> {
+    const record = { id, data, timestamp: Date.now() };
+    return await this.adapter.create(
+      'records',
+      id,
+      record,
+      {},
+      { stub: ctx.stub, logger: ctx.logging }
+    );
+  }
+
+  @Transaction(false)
+  async queryRecords(ctx: Context, owner: string): Promise<any[]> {
+    const query = {
+      selector: {
+        owner: owner
+      }
+    };
+
+    return await this.adapter.raw(
+      query,
+      true,
+      { stub: ctx.stub, logger: ctx.logging }
+    );
+  }
+}
+```
+
+### Emitting and Handling Events
+
+```typescript
+import { 
+  FabricContractRepositoryObservableHandler,
+  generateFabricEventName,
+  parseEventName
+} from '@decaf-ts/for-fabric';
+import { Context } from 'fabric-contract-api';
+import { OperationKeys } from '@decaf-ts/db-decorators';
+
+// In chaincode: Emit an event
+async function emitEvent(ctx: Context, tableName: string, id: string) {
+  const handler = new FabricContractRepositoryObservableHandler();
+  const logger = ctx.logging.getLogger('EventHandler');
+
+  await handler.updateObservers(
+    logger,
+    tableName,
+    OperationKeys.CREATE,
+    id,
+    { stub: ctx.stub }
+  );
+}
+
+// In client: Parse an event name
+function handleEvent(eventName: string, payload: Buffer) {
+  const { table, event, owner } = parseEventName(eventName);
+  const data = JSON.parse(payload.toString());
+
+  console.log(`Received ${event} event for ${table} with ID ${data.id}`);
+  if (owner) {
+    console.log(`Event owner: ${owner}`);
+  }
+}
+```
+
+For more detailed examples and API documentation, refer to the [API Reference](./docs/api/index.html).
+
+
+## Contracts APIs (Chaincode)
+
+The following examples are based on the contracts in for-fabric/src/contracts and reflect the patterns used by the unit/integration tests.
+
+### FabricCrudContract<M>
+
+Description: Base contract exposing CRUD endpoints for a model class. It uses Repository and DeterministicSerializer under the hood.
+
+```typescript
+import { Context, Transaction, Contract } from 'fabric-contract-api';
+import { model, ModelArg, required } from '@decaf-ts/decorator-validation';
+import { BaseModel, pk } from '@decaf-ts/core';
+import { FabricCrudContract } from '@decaf-ts/for-fabric/contracts';
+
+@model()
+class Person extends BaseModel {
+  @pk({ type: 'Number' })
+  id!: number;
+  @required() name!: string;
+  constructor(arg?: ModelArg<Person>) { super(arg); }
+}
+
+export class PersonContract extends FabricCrudContract<Person> {
+  constructor() {
+    super('PersonContract', Person);
+  }
+
+  @Transaction(false)
+  async ping(ctx: Context): Promise<string> {
+    // Uses FabricCrudContract.logFor
+    this.logFor(ctx).info('ping');
+    return 'pong';
+  }
+}
+```
+
+Usage in tests: see tests/unit/contracts.test.ts pattern where a SerializedCrudContract subclass is exercised; FabricCrudContract is similar but takes/returns objects instead of JSON strings.
+
+### SerializedCrudContract<M>
+
+Description: Same endpoints as FabricCrudContract but takes and returns JSON strings. Useful for simple clients. Based on tests/unit/contracts.test.ts.
+
+```typescript
+import { Context } from 'fabric-contract-api';
+import { model, ModelArg, required } from '@decaf-ts/decorator-validation';
+import { BaseModel, pk } from '@decaf-ts/core';
+import { SerializedCrudContract } from '@decaf-ts/for-fabric/contracts';
+
+@model()
+class TestModel extends BaseModel {
+  @pk({ type: 'Number' }) id!: number;
+  @required() name!: string;
+  @required() nif!: string;
+  constructor(arg?: ModelArg<TestModel>) { super(arg); }
+}
+
+export class TestModelContract extends SerializedCrudContract<TestModel> {
+  constructor() {
+    super('TestModelContract', TestModel);
+  }
+}
+
+// Example invocation (mirrors unit test usage)
+async function createExample(contract: TestModelContract, ctx: Context) {
+  const payload = new TestModel({ name: 'Alice', nif: '123456789' }).serialize();
+  const resultJson = await contract.create(ctx, payload);
+  const created = new TestModel(JSON.parse(resultJson));
+  return created;
+}
+```
+
+### FabricContractRepository<M>
+
+Description: Chaincode-side repository used inside contract methods to persist and query models.
+
+```typescript
+import { Context } from 'fabric-contract-api';
+import { Repo } from '@decaf-ts/core';
+import { model, required, ModelArg } from '@decaf-ts/decorator-validation';
+import { BaseModel, pk } from '@decaf-ts/core';
+import { FabricContractRepository } from '@decaf-ts/for-fabric/contracts';
+
+@model()
+class Asset extends BaseModel {
+  @pk() id!: string;
+  @required() owner!: string;
+  constructor(arg?: ModelArg<Asset>) { super(arg); }
+}
+
+export class AssetContract extends Contract {
+  private repo: Repo<Asset, any, any, any, any>;
+  constructor() {
+    super('AssetContract');
+    this.repo = new FabricContractRepository<Asset>(new (require('@decaf-ts/for-fabric').contracts.FabricContractAdapter)(), Asset);
+  }
+
+  @Transaction()
+  async Create(ctx: Context, id: string, owner: string): Promise<void> {
+    const m = new Asset({ id, owner });
+    await this.repo.create(m, ctx as any);
+  }
+
+  @Transaction(false)
+  async Read(ctx: Context, id: string): Promise<Asset> {
+    return this.repo.read(id, ctx as any);
+  }
+
+  @Transaction(false)
+  async QueryByOwner(ctx: Context, owner: string): Promise<Asset[]> {
+    return this.repo.raw({ selector: { owner } } as any, true, ctx as any);
+  }
+}
+```
+
+### FabricContractDBSequence
+
+Description: World-state backed sequences for generating incremental values.
+
+```typescript
+import { Context } from 'fabric-contract-api';
+import { FabricContractDBSequence } from '@decaf-ts/for-fabric/contracts';
+import { FabricContractAdapter } from '@decaf-ts/for-fabric/contracts';
+
+const adapter = new FabricContractAdapter();
+
+export class OrderContract extends Contract {
+  private orderSeq = new FabricContractDBSequence({
+    name: 'orderSeq',
+    type: 'Number',
+    startWith: 1,
+    incrementBy: 1,
+  }, adapter);
+
+  @Transaction()
+  async CreateOrder(ctx: Context): Promise<number> {
+    const next = await this.orderSeq.next(ctx as any);
+    // use next as order id
+    return next as number;
+  }
+
+  @Transaction(false)
+  async NextRange(ctx: Context, count: number): Promise<number[]> {
+    return (await this.orderSeq.range(count, ctx as any)) as number[];
+  }
+}
+```
+
+### FabricStatement<M,R>
+
+Description: Bridge to run Mango queries through the Fabric adapter and get typed models back; used internally by repositories and also directly in advanced cases. See tests/unit/erc20conttract.test.ts mocking CouchDBStatement processing.
+
+```typescript
+import { FabricStatement } from '@decaf-ts/for-fabric/contracts';
+import { FabricContractAdapter } from '@decaf-ts/for-fabric/contracts';
+import { FabricContractContext } from '@decaf-ts/for-fabric/contracts';
+import { MangoQuery } from '@decaf-ts/for-couchdb';
+import { Model } from '@decaf-ts/decorator-validation';
+
+class MyModel extends Model {}
+
+const adapter = new FabricContractAdapter();
+
+async function query(ctx: FabricContractContext) {
+  const stmt = new FabricStatement<MyModel, MyModel[]>(adapter, ctx);
+  const models = await stmt.raw<MyModel[]>({ selector: { type: 'MyModel' } } as MangoQuery);
+  return models;
+}
+```
+
+### ContractLogger
+
+Description: Context-aware logger bound to Fabric’s Context, honoring log levels.
+
+```typescript
+import { Context, Transaction } from 'fabric-contract-api';
+import { Contract } from 'fabric-contract-api';
+import { ContractLogger } from '@decaf-ts/for-fabric/contracts';
+
+export class LoggableContract extends Contract {
+  @Transaction()
+  async DoWork(ctx: Context): Promise<void> {
+    const log = new ContractLogger('LoggableContract', { level: 'info' }, ctx as any);
+    log.info('Starting work');
+    // ... work ...
+    log.debug('Finished');
+  }
+}
+```
+
+### FabricContractRepositoryObservableHandler
+
+Description: Emits Fabric events for repository operations. You can also use it directly to emit a custom event.
+
+```typescript
+import { FabricContractRepositoryObservableHandler } from '@decaf-ts/for-fabric/contracts';
+import { OperationKeys } from '@decaf-ts/db-decorators';
+import { FabricContractContext } from '@decaf-ts/for-fabric/contracts';
+import { MiniLogger } from '@decaf-ts/logging';
+
+async function emitExample(ctx: FabricContractContext) {
+  const handler = new FabricContractRepositoryObservableHandler();
+  const log = new MiniLogger('obs');
+  await handler.updateObservers(log as any, 'assets', OperationKeys.CREATE, 'asset1', ctx);
+}
+```
+
+### FabricContractContext
+
+Description: Access Fabric-specific context inside contracts.
+
+```typescript
+import { FabricContractContext } from '@decaf-ts/for-fabric/contracts';
+
+function readContext(ctx: FabricContractContext) {
+  const ts = ctx.timestamp; // Date from stub.getDateTimestamp()
+  const id = ctx.identity.getID();
+  ctx.logger.info(`Tx by ${id} at ${ts.toISOString()}`);
+}
+```
+
+### FabricERC20Contract (sample)
+
+Description: Full ERC20 implementation used in tests (see tests/unit/erc20conttract.test.ts).
+
+```typescript
+import { FabricERC20Contract } from '@decaf-ts/for-fabric/contracts';
+import { FabricContractContext } from '@decaf-ts/for-fabric/contracts';
+
+const contract = new FabricERC20Contract('TestToken');
+
+async function initAndRead(ctx: FabricContractContext) {
+  const created = await contract.Initialize(ctx, 'TestToken', 'TT', 18);
+  if (created) {
+    const name = await contract.TokenName(ctx);
+    const decimals = await contract.Decimals(ctx);
+    return { name, decimals };
+  }
+  throw new Error('Init failed');
+}
+```
+
+### Notes on tests as examples
+
+- tests/unit/contracts.test.ts shows creating a SerializedCrudContract and calling create(ctx, jsonPayload) with a mocked Fabric Context.
+- tests/unit/erc20conttract.test.ts demonstrates initializing the ERC20 contract and reading TokenName.
+- tests/integration/Serialized-Contract.test.ts shows end-to-end JSON-based CRUD flows via the serialized contract, including create, read, update and rich queries.
+
+These patterns are mirrored in the examples above to ensure correctness and consistency with the repository’s test suite.
+
+
+### Related
+
+[![Readme Card](https://github-readme-stats.vercel.app/api/pin/?username=decaf-ts&repo=ts-workspace)](https://github.com/decaf-ts/ts-workspace)
+
+### Social
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/decaf-ts/)
+
+
+
+
+#### Languages
+
+![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
+![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black)
+![NodeJS](https://img.shields.io/badge/Node.js-43853D?style=for-the-badge&logo=node.js&logoColor=white)
+![ShellScript](https://img.shields.io/badge/Shell_Script-121011?style=for-the-badge&logo=gnu-bash&logoColor=white)
+
+## Getting help
+
+If you have bug reports, questions or suggestions please [create a new issue](https://github.com/decaf-ts/ts-workspace/issues/new/choose).
+
+## Contributing
+
+I am grateful for any contributions made to this project. Please read [this](./workdocs/98-Contributing.md) to get started.
+
+## Supporting
+
+The first and easiest way you can support it is by [Contributing](./workdocs/98-Contributing.md). Even just finding a typo in the documentation is important.
+
+Financial support is always welcome and helps keep both me and the project alive and healthy.
+
+So if you can, if this project in any way. either by learning something or simply by helping you save precious time, please consider donating.
+
+## License
+
+This project is released under the [MIT License](./LICENSE.md).
+
+By developers, for developers...