Skip to content

Commit 88054d3

Browse files
niemyjskiniemyjski
committed
Added initial docs
1 parent 44be85e commit 88054d3

29 files changed

+14024
-37
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- '.github/workflows/docs.yml'
10+
11+
concurrency:
12+
group: pages
13+
cancel-in-progress: false
14+
15+
jobs:
16+
deploy-docs:
17+
runs-on: ubuntu-latest
18+
permissions:
19+
contents: read
20+
pages: write
21+
id-token: write
22+
23+
environment:
24+
name: github-pages
25+
url: ${{ steps.deployment.outputs.page_url }}
26+
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v6
30+
with:
31+
fetch-depth: 0
32+
33+
- name: Setup Node.js
34+
uses: actions/setup-node@v6
35+
with:
36+
node-version: 24
37+
38+
- name: Clean npm cache and dependencies
39+
run: |
40+
rm -rf node_modules package-lock.json
41+
npm cache clean --force
42+
working-directory: docs
43+
44+
- name: Install dependencies
45+
run: npm install --force
46+
working-directory: docs
47+
48+
- name: Build documentation
49+
run: npm run build
50+
working-directory: docs
51+
env:
52+
NODE_ENV: production
53+
54+
- name: Setup Pages
55+
uses: actions/configure-pages@v5
56+
57+
- name: Upload artifact
58+
uses: actions/upload-pages-artifact@v4
59+
with:
60+
path: docs/.vitepress/dist
61+
62+
- name: Deploy to GitHub Pages
63+
id: deployment
64+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@
88
artifacts
99
.vs/
1010

11+
# Node
12+
node_modules/
13+
npm-debug.log
14+
yarn-error.log
15+
docs/.vitepress/dist/
16+
docs/.vitepress/cache/
17+
1118
# MSTest test Results
1219
[Tt]est[Rr]esult*/
1320

@@ -51,4 +58,5 @@ _NCrunch_*
5158
# Rider auto-generates .iml files, and contentModel.xml
5259
**/.idea/**/*.iml
5360
**/.idea/**/contentModel.xml
54-
**/.idea/**/modules.xml
61+
**/.idea/**/modules.xml
62+
**/.idea/copilot/chatSessions/

‎README.md‎

Lines changed: 191 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,194 @@
55
[![feedz.io](https://img.shields.io/badge/endpoint.svg?url=https%3A%2F%2Ff.feedz.io%2Ffoundatio%2Ffoundatio%2Fshield%2FFoundatio.Repositories%2Flatest)](https://f.feedz.io/foundatio/foundatio/packages/Foundatio.Repositories/latest/download)
66
[![Discord](https://img.shields.io/discord/715744504891703319)](https://discord.gg/6HxgFCx)
77

8-
Generic repository contract and implementations. Currently only implemented for Elasticsearch, but there are plans for other implementations.
9-
10-
# Features
11-
12-
- Simple document repository pattern
13-
- CRUD operations: Add, Save, Remove, Get
14-
- Supports patch operations
15-
- JSON patch
16-
- Partial document patch
17-
- Painless script patch (Elasticsearch)
18-
- Can be applied in bulk using queries
19-
- Async events that can be wired up and listened to outside of the repos
20-
- Caching (real-time invalidated before save and stored in distributed cache)
21-
- Message bus support (enables real-time apps sends messages like doc updated up to the client so they know to update the UI)
22-
- Searchable that works with Foundatio.Parsers lib for dynamic querying, filtering, sorting and aggregations
23-
- Document validation
24-
- Document versioning
25-
- Soft deletes
26-
- Auto document created and updated dates
27-
- Document migrations
28-
- Elasticsearch implementation
29-
- Plan to add additional implementations (Postgres with Marten would be a good fit)
30-
- Elasticsearch index configuration allows simpler and more organized configuration
31-
- Schema versioning
32-
- Parent child queries
33-
- Daily and monthly index strategies
34-
- Supports different consistency models (immediate, wait or eventual)
35-
- Can be configured at the index type or individual query level
36-
- Query builders used to make common ways of querying data easier and more portable between repo implementations
37-
- Can still use raw Elasticsearch queries
38-
- Field includes and excludes to make the response size smaller
39-
- Field conditions query builder
40-
- Paging including snapshot paging support
41-
- Dynamic field resolution for using friendly names of dynamically generated fields
42-
- Jobs for index maintenance, snapshots, reindex
43-
- Strongly typed field access (using lambda expressions) to enable refactoring
8+
# Foundatio.Repositories
9+
10+
A production-grade repository pattern library for .NET with Elasticsearch implementation. Built on [Foundatio](https://github.com/FoundatioFx/Foundatio) building blocks, it provides a clean abstraction over data access with powerful features like caching, messaging, soft deletes, and versioning.
11+
12+
📖 **[Full Documentation](https://repositories.foundatio.dev)**
13+
14+
## Installation
15+
16+
```bash
17+
dotnet add package Foundatio.Repositories.Elasticsearch
18+
```
19+
20+
## Quick Start
21+
22+
### 1. Define Your Entity
23+
24+
```csharp
25+
using Foundatio.Repositories.Models;
26+
27+
public class Employee : IIdentity, IHaveDates, ISupportSoftDeletes
28+
{
29+
public string Id { get; set; } = string.Empty;
30+
public string Name { get; set; } = string.Empty;
31+
public string Email { get; set; } = string.Empty;
32+
public int Age { get; set; }
33+
public DateTime CreatedUtc { get; set; }
34+
public DateTime UpdatedUtc { get; set; }
35+
public bool IsDeleted { get; set; }
36+
}
37+
```
38+
39+
### 2. Create Index Configuration
40+
41+
```csharp
42+
using Foundatio.Repositories.Elasticsearch.Configuration;
43+
44+
public sealed class EmployeeIndex : VersionedIndex<Employee>
45+
{
46+
public EmployeeIndex(IElasticConfiguration configuration)
47+
: base(configuration, "employees", version: 1) { }
48+
49+
public override TypeMappingDescriptor<Employee> ConfigureIndexMapping(
50+
TypeMappingDescriptor<Employee> map)
51+
{
52+
return map
53+
.Dynamic(false)
54+
.Properties(p => p
55+
.SetupDefaults()
56+
.Text(f => f.Name(e => e.Name).AddKeywordAndSortFields())
57+
.Text(f => f.Name(e => e.Email).AddKeywordAndSortFields())
58+
.Number(f => f.Name(e => e.Age).Type(NumberType.Integer))
59+
);
60+
}
61+
}
62+
```
63+
64+
### 3. Create Repository
65+
66+
```csharp
67+
using Foundatio.Repositories;
68+
using Foundatio.Repositories.Elasticsearch;
69+
70+
public interface IEmployeeRepository : ISearchableRepository<Employee> { }
71+
72+
public class EmployeeRepository : ElasticRepositoryBase<Employee>, IEmployeeRepository
73+
{
74+
public EmployeeRepository(MyElasticConfiguration configuration)
75+
: base(configuration.Employees) { }
76+
}
77+
```
78+
79+
### 4. Use the Repository
80+
81+
```csharp
82+
// Add
83+
var employee = await repository.AddAsync(new Employee
84+
{
85+
Name = "John Doe",
86+
Email = "john@example.com",
87+
Age = 30
88+
});
89+
90+
// Query
91+
var results = await repository.FindAsync(q => q
92+
.FilterExpression("age:>=25")
93+
.SortExpression("name"));
94+
95+
// Update
96+
employee.Age = 31;
97+
await repository.SaveAsync(employee);
98+
99+
// Soft delete
100+
employee.IsDeleted = true;
101+
await repository.SaveAsync(employee);
102+
103+
// Hard delete
104+
await repository.RemoveAsync(employee);
105+
```
106+
107+
## Features
108+
109+
### Repository Pattern
110+
- **`IReadOnlyRepository<T>`** - Read operations (Get, Find, Count, Exists)
111+
- **`IRepository<T>`** - Write operations (Add, Save, Remove, Patch)
112+
- **`ISearchableRepository<T>`** - Dynamic querying with filters, sorting, and aggregations
113+
114+
### Patch Operations
115+
- **JSON Patch** - RFC 6902 compliant patch operations
116+
- **Partial Patch** - Update specific fields without loading the full document
117+
- **Script Patch** - Elasticsearch Painless scripts for complex updates
118+
- **Bulk Patching** - Apply patches to multiple documents via query
119+
120+
### Caching
121+
- Built-in distributed caching with automatic invalidation
122+
- Real-time cache consistency via message bus
123+
- Configurable cache expiration and custom cache keys
124+
125+
### Message Bus
126+
- Entity change notifications (`EntityChanged` messages)
127+
- Real-time updates for event-driven architectures
128+
- Soft delete transition detection (`ChangeType.Removed`)
129+
130+
### Soft Deletes
131+
- Automatic query filtering based on `IsDeleted`
132+
- Three query modes: `ActiveOnly`, `DeletedOnly`, `All`
133+
- Restore capability for soft-deleted documents
134+
135+
### Document Versioning
136+
- Optimistic concurrency control
137+
- Automatic version conflict detection
138+
- Retry patterns for conflict resolution
139+
140+
### Index Management
141+
- **`Index<T>`** - Basic index configuration
142+
- **`VersionedIndex<T>`** - Schema versioning with migrations
143+
- **`DailyIndex<T>`** - Time-series with daily partitioning
144+
- **`MonthlyIndex<T>`** - Time-series with monthly partitioning
145+
146+
### Event System
147+
- `DocumentsAdding` / `DocumentsAdded`
148+
- `DocumentsSaving` / `DocumentsSaved`
149+
- `DocumentsRemoving` / `DocumentsRemoved`
150+
- `DocumentsChanging` / `DocumentsChanged`
151+
- `BeforeQuery` - Query interception
152+
- `BeforePublishEntityChanged` - Notification interception
153+
154+
### Additional Features
155+
- Document validation with custom validators
156+
- Migrations for data schema evolution
157+
- Jobs for index maintenance, snapshots, and cleanup
158+
- Custom fields for tenant-specific data
159+
- Parent-child document relationships
160+
- Aggregations and analytics
161+
162+
## Documentation
163+
164+
Visit the [full documentation](https://repositories.foundatio.dev) for detailed guides:
165+
166+
- [Getting Started](https://repositories.foundatio.dev/guide/getting-started)
167+
- [Repository Pattern](https://repositories.foundatio.dev/guide/repository-pattern)
168+
- [Elasticsearch Setup](https://repositories.foundatio.dev/guide/elasticsearch-setup)
169+
- [CRUD Operations](https://repositories.foundatio.dev/guide/crud-operations)
170+
- [Querying](https://repositories.foundatio.dev/guide/querying)
171+
- [Configuration](https://repositories.foundatio.dev/guide/configuration)
172+
- [Validation](https://repositories.foundatio.dev/guide/validation)
173+
- [Caching](https://repositories.foundatio.dev/guide/caching)
174+
- [Message Bus](https://repositories.foundatio.dev/guide/message-bus)
175+
- [Patch Operations](https://repositories.foundatio.dev/guide/patch-operations)
176+
- [Soft Deletes](https://repositories.foundatio.dev/guide/soft-deletes)
177+
- [Versioning](https://repositories.foundatio.dev/guide/versioning)
178+
- [Index Management](https://repositories.foundatio.dev/guide/index-management)
179+
- [Migrations](https://repositories.foundatio.dev/guide/migrations)
180+
- [Jobs](https://repositories.foundatio.dev/guide/jobs)
181+
- [Custom Fields](https://repositories.foundatio.dev/guide/custom-fields)
182+
183+
## Sample Application
184+
185+
See the [sample Blazor application](samples/Foundatio.SampleApp) for a complete working example.
186+
187+
## Related Projects
188+
189+
- [Foundatio](https://github.com/FoundatioFx/Foundatio) - Core building blocks (caching, messaging, queues, jobs)
190+
- [Foundatio.Parsers](https://github.com/FoundatioFx/Foundatio.Parsers) - Query parsing for dynamic filtering
191+
192+
## Contributing
193+
194+
We welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md) for details.
195+
196+
## License
197+
198+
Licensed under the Apache License, Version 2.0. See [LICENSE.txt](LICENSE.txt) for details.

0 commit comments

Comments
 (0)