@smartsoft001/domain-core

Installation

npm i @smartsoft001/domain-core

Repositories

IItemRepository

create - Creates a new entity in the storage system.

returns a Promise<void> that resolves when the entity is successfully created.

createMany - Creates multiple entities in the storage system.

returns a Promise<void> that resolves when all entities are successfully created.

update - Updates an existing entity in the storage system.

returns a Promise<void> that resolves when the entity is successfully updated.

updatePartial - Partially updates an existing entity in the storage system.

Partial<T>& { id: string }

returns a Promise<void> that resolves when the entity is successfully updated.

updatePartialManyByCriteria - Partially updates multiple entities that match the specified criteria.

Partial<T>

returns a Promise<void> that resolves when the entities are successfully updated.

updatePartialManyBySpecification - Partially updates multiple entities that match the specified specification.

Partial<T>

returns a Promise<void> that resolves when the entities are successfully updated.

delete - Deletes an entity from the storage system by its ID.

returns a Promise<void> that resolves when the entity is successfully deleted.

getById - Retrieves an entity from the storage system by its ID.

returns a Promise<T> that resolves to the retrieved entity.

getByCriteria - Retrieves entities from the storage system that match the specified criteria.

returns a Promise<{ data: T[]; totalCount: number }> that resolves to an object containing the matching entities and the total count.

getBySpecification - Retrieves entities from the storage system that match the specified specification.

returns a Promise<{ data: T[]; totalCount: number }> that resolves to an object containing the matching entities and the total count.

countBySpecification - Counts the number of entities in the storage system that match the specified specification.

returns a Promise<number> that resolves to a count of matching entities.

clear - Counts the number of entities in the storage system that match the specified specification.

returns a Promise<void> that resolves when the storage system is cleared.

changesByCriteria - Returns an observable that emits changes to entities that match the specified criteria.

returns a Observable<any> that emits changes to the matching entities.

IAttachmentRepository

upload - Uploads a file to the storage system.

{ streamCallback?: (r: any) => void }

returns a Promise<void> that when the upload is complete. throws an error if the upload fails.

Example usage with MongoDB implementation:

const repository = new MongoAttachmentRepository(config);

const fileStream = fs.createReadStream('/path/to/file');

await repository.upload(
  {
    id: 'unique-file-id',
    fileName: 'example.txt',
    stream: fileStream,
    mimeType: 'text/plain',
    encoding: 'utf-8',
  },
  {
    streamCallback: (writeStream) => {
      console.log('Upload started');
    },
  },
);

console.log('File uploaded successfully');

getInfo - Retrieves metadata information about a file stored in the storage system.

returns a Promise<{ fileName: string, contentType: string, length: number } | null> that resolves to an object containing file metadata, or null if the file is not found.

throws an error if retrieving the file information fails.

getStream - Retrieves a stream for downloading a file from the storage system.

{ start: number; end: number }

returns a Promise<any> that resolves to a readable stream of the file.

throws an error if retrieving the file stream fails.

delete - Deletes a file from the storage system.

returns a Promise<void> that resolves when the file has been successfully deleted.

throws an error if the deletion fails.

Unit of work

IUnitOfWork

An abstract class that runs a set of repository calls as one atomic unit, so they either all commit or all roll back. It is implemented per storage technology; @smartsoft001/mongo binds MongoUnitOfWork to it.

scope - Executes a set of operations within a transactional scope.

(transaction: ITransaction) => Promise<void>

returns a Promise<void> that resolves once the transaction has been committed. throws an error if the transaction fails, in which case every operation is rolled back.

await this.unitOfWork.scope(async (transaction) => {
  await this.itemRepository.updatePartial(
    { id: firstId, status: 'finished' },
    user,
    { transaction },
  );

  await this.itemRepository.updatePartial(
    { id: secondId, status: 'finished' },
    user,
    { transaction },
  );
});

ITransaction

The context handed to a scope callback. It carries a single property, connection, whose type depends on the storage implementation, and it is what IItemRepositoryOptions.transaction expects.

Specifications

A specification is an object with a criteria property that a repository turns into a query. getBySpecification, countBySpecification and updatePartialManyBySpecification all take one, and SpecificationService in @smartsoft001/utils evaluates the same object in memory.

const spec = new AndSpecification(
  new BasicSpecification({ status: 'finished' }),
  new OrSpecification(
    new BasicSpecification({ owner: 'ann' }),
    new BasicSpecification({ owner: 'bob' }),
  ),
);

const { data, totalCount } = await repository.getBySpecification(spec);

ISpecification, the interface all four implement, is re-exported here from @smartsoft001/models so that the domain layer can be written against this package alone.

Errors

Two error classes the domain layer throws and the HTTP layer maps to status codes. Each one carries a type property holding its own constructor, which is how a filter recognises it after the class has crossed a package boundary.

Interfaces