@decaf-ts/for-fabric 0.0.2 → 0.0.4

package/LICENSE.md

@@ -1,22 +1,164 @@
-MIT License
+Mozilla Public License Version 2.0
 
-Copyright (c) 2025 Tiago Venceslau and Contributors
+1. Definitions
 
-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:
+"Contributor"
+    means each individual or legal entity that creates, contributes to the
+    creation of, or owns Covered Software.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+"Contributor Version"
+    means the combination of the Contributions of others (if any) used by a
+    Contributor and that particular Contributor's Contribution.
 
-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.
+"Covered Software"
+    means Source Code Form to which the initial Contributor has attached the
+    notice in Exhibit A, the Executable Form of such Source Code Form, and
+    Modifications of such Source Code Form.
 
+"Executable Form"
+    means any form of the work other than Source Code Form.
+
+"Larger Work"
+    means a work which combines Covered Software with other material, in a
+    separate file or files, that is not Covered Software.
+
+"License"
+    means this document.
+
+"Licensable"
+    means having the right to grant, to the maximum extent possible, whether
+    at the time of the making or afterwards, any and all of the rights
+    conveyed by this License.
+
+"Modifications"
+    means any addition to or deletion from the contents of Covered Software
+    or any new file that contains Covered Software.
+
+"Patent Claims"
+    means any patent claim(s), now owned or hereafter acquired, including
+    without limitation, method, process, and apparatus claims, in any patent
+    Licensable by grantor.
+
+"Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU Lesser
+    General Public License, Version 2.1, the European Union Public License 1.1,
+    or any subsequent versions of those licenses that are designated as a
+    Secondary License in the notice in Exhibit A.
+
+"Source Code Form"
+    means the form of the work preferred for making modifications.
+
+"You" (or "Your")
+    means an individual or a legal entity exercising rights under, and
+    complying with all of the terms of, this License. For legal entities,
+    "You" includes any entity that controls, is controlled by, or is under
+    common control with You. For purposes of this definition, "control"
+    means (a) the power, direct or indirect, to cause the direction or
+    management of such entity, whether by contract or otherwise, or (b)
+    ownership of more than fifty percent (50%) of the outstanding shares or
+    beneficial ownership of such entity.
+
+2. License Grants and Conditions
+
+Each Contributor hereby grants You a world-wide, royalty-free, non-exclusive
+license:
+
+  a. under intellectual property rights (other than patent or trademark)
+     Licensable by such Contributor to use, reproduce, make available,
+     modify, display, perform, distribute, and otherwise exploit its
+     Contributions, either on an exclusive or non-exclusive basis; and
+
+  b. under Patent Claims to make, use, sell, offer for sale, have made,
+     import, and otherwise transfer the Contribution(s) of such
+     Contributor, if any, in the Covered Software.
+
+This license does not grant rights to any trademarks, service marks, or logos
+of any Contributor (except as may be necessary to comply with the notice
+requirements in Section 3.4).
+
+3. Distribution Obligations
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under the
+terms of this License. You must inform recipients that the Source Code Form
+of the Covered Software is governed by the terms of this License and include
+a copy of this License in or with the Source Code Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+  a. such Covered Software must also be made available in Source Code Form,
+     as described in Section 3.1, and You must inform recipients of the
+     Executable Form how to obtain a complete copy of the corresponding
+     Source Code Form in a reasonable manner on or through a medium
+     customarily used for software exchange; and
+
+  b. You may distribute the Executable Form under terms of your choice,
+     provided that You do not attempt to limit or alter the recipients'
+     rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a work that combines Covered Software with
+other material, and distribute the Larger Work as a single product. In such
+case, the Covered Software must still be made available under this License
+and must include the notices described in Exhibit A relating to the Covered
+Software.
+
+3.4. Notices
+
+You must cause each file that You distribute containing Covered Software to
+carry the legal notices described in Exhibit A.
+
+4. Incompatible With Secondary Licenses
+
+If the Covered Software is made available under the terms of this License
+and also made available under the terms of a Secondary License, then the
+terms of the Secondary License apply to the Covered Software in addition to
+this License to the extent the Secondary License grants additional
+permissions. If the Covered Software is not made available under a Secondary
+License, then this License governs its use.
+
+5. Disclaimer of Warranty
+
+Covered Software is provided "as is" without warranty of any kind, either
+express or implied, including, but not limited to, the implied warranties of
+merchantability, fitness for a particular purpose, and noninfringement.
+
+6. Limitation of Liability
+
+In no event and under no legal theory, whether in tort (including
+negligence), contract, or otherwise, unless required by applicable law (such
+as deliberate and grossly negligent acts) or agreed to in writing, shall any
+Contributor be liable to You for damages, including any direct, indirect,
+special, incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the Covered
+Software (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the
+possibility of such damages.
+
+7. Termination
+
+This License and the rights granted hereunder will terminate automatically
+if You fail to comply with terms of this License and do not cure such
+breach within thirty (30) days of becoming aware of the breach.
+
+8. Miscellaneous
+
+This License constitutes the entire agreement between the parties with
+respect to the subject matter hereof. If any provision of this License is
+held to be unenforceable, that provision shall be reformed only to the
+extent necessary to make it enforceable. The headings are for convenience
+only and do not affect the interpretation.
+
+Exhibit A - Source Code Form License Notice
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+  Copyright (c) 2025 Tiago Venceslau and Contributors

package/README.md

@@ -1,7 +1,7 @@
 [![Banner](./workdocs/assets/Banner.png)](https://decaf-ts.github.io/ts-workspace/)
-## Hyperledger Fabric Contracts for DECAF
+## Hyperledger Fabric Integration 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.
+A TypeScript library that provides seamless integration with Hyperledger Fabric networks, offering both client-side connectivity and chaincode contract development capabilities. It extends the DECAF database abstraction framework to work with Fabric's ledger, enabling consistent data access patterns across different storage technologies.
 
 
 ![Licence](https://img.shields.io/github/license/decaf-ts/for-fabric.svg?style=plastic)
@@ -29,48 +29,39 @@ 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.
+The @decaf-ts/for-fabric library provides a comprehensive integration layer between the DECAF framework and Hyperledger Fabric blockchain networks. It is designed to simplify the development of both client applications that interact with Fabric networks and chaincode (smart contracts) that run on those networks.
 
-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.
+#### Client-Side Features
 
-Contracts building blocks identified in src/contracts:
+The client module offers a robust set of tools for connecting to and interacting with Fabric networks:
 
-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.
+- **FabricAdapter**: Extends the CouchDBAdapter to provide a familiar interface for CRUD operations against Fabric chaincode. It handles connection management, transaction submission, and query evaluation.
 
-2) Logging
-- ContractLogger: MiniLogger-compatible logger bound to the Fabric contract Context. It honors log levels and forwards to the underlying Fabric logger.
+- **FabricDispatch**: Listens for and processes events emitted by Fabric chaincode, enabling real-time updates and event-driven architectures.
 
-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.
+- **Fabric File System Utilities**: Simplifies working with Fabric identities, certificates, and private keys, with support for both Node.js and browser environments.
 
-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.
+#### Chaincode Features
 
-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.
+The contracts module provides a framework for developing Fabric chaincode with TypeScript:
 
-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.
+- **FabricContractAdapter**: Adapts the DECAF database interface to work within Fabric chaincode, providing access to the state database.
 
-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.
+- **FabricContractRepository**: Implements the Repository pattern for Fabric chaincode, enabling model-driven data access.
 
-With these components you can build robust chaincode while keeping code concise, testable, and aligned with DECAF’s architecture.
+- **FabricCrudContract**: An abstract base class that provides standard CRUD operations for chaincode models, reducing boilerplate code.
+
+- **Event Handling**: Built-in support for emitting and handling chaincode events, facilitating communication between chaincode and client applications.
+
+#### Integration with DECAF
+
+This library seamlessly integrates with other DECAF components:
+
+- Uses the decorator-validation library for model validation
+- Extends the db-decorators framework for consistent data access
+- Leverages the core DECAF patterns and abstractions
+
+By providing a consistent interface across different storage technologies, @decaf-ts/for-fabric enables developers to write applications that can work with both traditional databases and blockchain ledgers with minimal code changes.
 
 
 ### How to Use
@@ -356,256 +347,6 @@ function handleEvent(eventName: string, payload: Buffer) {
 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)
@@ -644,4 +385,4 @@ So if you can, if this project in any way. either by learning something or simpl
 
 This project is released under the [MIT License](./LICENSE.md).
 
-By developers, for developers...
+By developers, for developers...