{"id":13808791,"url":"https://github.com/politie/ngx-sherlock","last_synced_at":"2025-05-14T03:31:35.250Z","repository":{"id":26744635,"uuid":"109682144","full_name":"politie/ngx-sherlock","owner":"politie","description":"ngx-sherlock is an Angular tooling library to be used with the @politie/sherlock distributed reactive state management library.","archived":false,"fork":false,"pushed_at":"2024-06-06T07:17:51.000Z","size":4167,"stargazers_count":6,"open_issues_count":1,"forks_count":4,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-08-04T01:10:01.886Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/politie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-06T10:42:07.000Z","updated_at":"2024-06-06T19:54:53.000Z","dependencies_parsed_at":"2024-08-04T01:09:44.219Z","dependency_job_id":"01a1672d-6e9e-4fcf-b632-c11d8e8a7b5f","html_url":"https://github.com/politie/ngx-sherlock","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/politie%2Fngx-sherlock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/politie%2Fngx-sherlock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/politie%2Fngx-sherlock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/politie%2Fngx-sherlock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/politie","download_url":"https://codeload.github.com/politie/ngx-sherlock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225273274,"owners_count":17448076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T01:01:52.067Z","updated_at":"2024-11-19T00:31:06.260Z","avatar_url":"https://github.com/politie.png","language":"TypeScript","funding_links":[],"categories":["State Management"],"sub_categories":["Other State Libraries"],"readme":"# Ngx Sherlock\n\n[![CI](https://github.com/politie/ngx-sherlock/actions/workflows/build.yml/badge.svg)](https://github.com/politie/ngx-sherlock/actions/workflows/build.yml)\n[![Known Vulnerabilities](https://snyk.io/test/github/politie/ngx-sherlock/badge.svg)](https://snyk.io/test/github/politie/ngx-sherlock)\n[![npm version](https://img.shields.io/npm/v/@politie/ngx-sherlock)](https://www.npmjs.com/package/@politie/ngx-sherlock)\n[![license](https://img.shields.io/npm/l/@politie/ngx-sherlock?color=blue)](https://github.com/politie/ngx-sherlock/blob/main/LICENSE)\n\n**NgxSherlock** is a set of Angular bindings for the [Sherlock](https://github.com/politie/sherlock)\n reactive state management library.\n\n## Usage\n\n### Installation\n\nInstall **NgxSherlock** by running:\n\n```bash\nnpm install @politie/ngx-sherlock\n```\n\nAdd the `NgxSherlockModule` to your `AppModule`:\n\n```typescript\nimport { NgModule } from '@angular/core';\nimport { NgxSherlockModule } from '@politie/ngx-sherlock';\n\n@NgModule({\n    imports: [NgxSherlockModule],\n    ...\n})\nexport class AppModule { }\n```\n\n### `autoDetectChanges`\n\n**Signature**:\n\n```typescript\nclass AutoChangeDetectorService {\n    init(): Promise\u003cvoid\u003e;\n}\n```\n\nThe `AutoChangeDetectorService` enables automatic change detection when using Sherlock Derivables, even when using the OnPush change-detection-strategy. The alternative is to use the `value`-pipe which is explained below. When using the `AutoChangeDetectorService` it is no longer needed to use the pipe.\n\nThe service needs to be instantiated once for each component. This is accomplished by mentioning it in the `providers` section of the Component metadata. It will detach the default ChangeDetector and re-enables change detection once `#init()` is called. This will ensure that change detection is wrapped with Sherlock magic.\n\nThe `AutoChangeDetectorService` service guarantees model and view fidelity, meaning one can easily use Angular's forms and template functionality.\n\n#### Example\n\n`trusty-sidekick.component.ts`:\n\n```typescript\nimport { Component, ChangeDetectionStrategy, ChangeDetectorRef, Input } from '@angular/core';\nimport { AutoChangeDetectorService } from '@politie/ngx-sherlock';\nimport { atom, Derivable } from '@politie/sherlock';\n\n@Component({\n    selector: 'trusty-sidekick',\n    template: `\n        \u003cinput type=\"text\" [(ngModel)]=\"firstname$.value\" placeholder=\"First name\"\u003e\n        \u003cinput type=\"text\" [(ngModel)]=\"surname$.value\" placeholder=\"Surname\"\u003e\n        \u003csidekick-greeter [name]=\"sidekick$\"\u003e\u003c/sidekick-greeter\u003e\n    `,\n    providers: [AutoChangeDetectorService],\n})\nexport class TrustySidekickComponent {\n    readonly sidekick$ = atom({ firstname: 'John', surname: 'Watson' });\n    readonly firstname$ = this.sidekick$.pluck('firstname');\n    readonly surname$ = this.sidekick$.pluck('surname');\n\n    // Here we call AutoChangeDetectorService#init which will automatically react on changes in the state of\n    // any used derivable.\n    constructor(autoCD: AutoChangeDetectorService) { autoCD.init(); }\n}\n\n@Component({\n    selector: 'sidekick-greeter',\n    template: `\n        \u003ch2 *ngIf=\"!beObnoxious\"\u003eWell hello there, {{ name.value.firstname }} {{ name.value.surname }}!\u003c/h2\u003e\n        \u003ch2 *ngIf=\"beObnoxious\"\u003eSo good of you to finally join us, {{ name.value.surname }}...\u003c/h2\u003e\n        \n        \u003cbutton (click)=\"toggle()\"\u003eChange mood\u003c/button\u003e     \n    `,\n    changeDetection: ChangeDetectionStrategy.OnPush,\n    providers: [AutoChangeDetectorService],\n})\nexport class SidekickGreeterComponent implements OnInit {\n    @Input() name: Derivable\u003c{ firstname: string, surname: string }\u003e;\n    obnoxious$ = atom(false);\n\n    get beObnoxious() {\n        return this.obnoxious$.get();\n    }\n\n    constructor(autoCD: AutoChangeDetectorService) { autoCD.init(); }\n\n    toggle() {\n        this.obnoxious$.swap(mood =\u003e !mood);\n    }\n}\n```\n\n---\n\n### `ValuePipe`\n\nThe `ValuePipe` unwraps a `Derivable` or `DerivableProxy` value and triggers the `ChangeDetectorRef` whenever an internal value changes\nand a change detection cycle is needed. This allows a component to have an `OnPush` `ChangeDetectionStrategy`, greatly increasing\nperformance.\n\n#### Example\n\n`my.component.html`:\n\n```html\n\u003ch1\u003eMy awesome counter\u003c/h1\u003e\n\u003cp\u003eWe're already at: \u003cstrong\u003e{{ counter$ | value }}\u003c/strong\u003e\u003c/p\u003e\n```\n\n`my.component.ts`:\n\n```typescript\nimport { Component, OnInit, ChangeDetectionStrategy } from '@angular/core';\nimport { atom } from '@politie/sherlock';\n\n@Component({\n    selector: 'my-component';\n    templateUrl: 'my.component.html',\n    changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class MyComponent implements OnInit {\n    readonly counter$ = atom(0);\n\n    ngOnInit() {\n        setInterval(() =\u003e this.counter$.swap(i =\u003e i++), 1000);\n    }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolitie%2Fngx-sherlock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolitie%2Fngx-sherlock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolitie%2Fngx-sherlock/lists"}