@bhofstaetter/payloadcms-repository 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benedikt Hofstätter
+
+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,98 @@
+# payload-repository
+
+Opinionated repository and query object wrapper around Payload's Local API.
+
+## Installation
+
+```sh
+npm install @bhofstaetter/payloadcms-repository
+```
+
+## Usage
+
+Pass your generated Payload `Config` type as the first type argument to get full type safety on fields, select, and return types.
+
+### CollectionQuery
+
+Extend `CollectionQuery` to encapsulate domain-specific query logic for a collection:
+
+```ts
+import type {BasePayload} from 'payload';
+import type {Config} from '@/payload-types';
+import {CollectionQuery} from '@bhofstaetter/payloadcms-repository';
+
+class PostsQuery extends CollectionQuery<Config, 'posts'> {
+    constructor(payload: BasePayload) {
+        super(payload, 'posts');
+    }
+
+    create(title: string) {
+        return this.repository.create({title});
+    }
+
+    findAll() {
+        return this.repository.find();
+    }
+
+    findById(id: number) {
+        return this.repository.findById(id);
+    }
+
+    findPublished() {
+        return this.repository.find({where: {status: {equals: 'published'}}});
+    }
+
+    publish(id: number) {
+        return this.repository.updateById(id, {status: 'published'});
+    }
+
+    deleteById(id: number) {
+        return this.repository.deleteById(id);
+    }
+}
+
+// Usage
+const postsQuery = new PostsQuery(payload);
+
+const post = await postsQuery.create('Hello World');
+const published = await postsQuery.findPublished();
+await postsQuery.publish(post.id);
+```
+
+### GlobalQuery
+
+Extend `GlobalQuery` to encapsulate domain-specific query logic for a global:
+
+```ts
+import type {BasePayload} from 'payload';
+import type {Config} from '@/payload-types';
+import {GlobalQuery} from '@bhofstaetter/payloadcms-repository';
+
+class SettingsQuery extends GlobalQuery<Config, 'settings'> {
+    constructor(payload: BasePayload) {
+        super(payload, 'settings');
+    }
+
+    get() {
+        return this.repository.find();
+    }
+
+    setSiteTitle(title: string) {
+        return this.repository.update({siteTitle: title});
+    }
+}
+
+// Usage
+const settingsQuery = new SettingsQuery(payload);
+
+const settings = await settingsQuery.get();
+await settingsQuery.setSiteTitle('My Site');
+```
+
+## License
+
+MIT
+
+## Todo
+
+- [ ] Github Actions

package/dist/collection/CollectionQuery.d.ts

@@ -0,0 +1,7 @@
+import type { BasePayload, CollectionSlug } from 'payload';
+import type { AnyCollectionConfig } from '@/types';
+import { CollectionRepository } from './CollectionRepository';
+export declare abstract class CollectionQuery<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug> {
+    protected readonly repository: CollectionRepository<TConfig, TSlug>;
+    protected constructor(payload: BasePayload, collectionSlug: TSlug);
+}

package/dist/collection/CollectionQuery.js

@@ -0,0 +1,7 @@
+import { CollectionRepository } from './CollectionRepository';
+export class CollectionQuery {
+    repository;
+    constructor(payload, collectionSlug) {
+        this.repository = new CollectionRepository(payload, collectionSlug);
+    }
+}

package/dist/collection/CollectionRepository.d.ts

@@ -0,0 +1,64 @@
+import type { BasePayload, BulkOperationResult, CollectionSlug, DataFromCollectionSlug, PaginatedDistinctDocs, PaginatedDocs, RequiredDataFromCollectionSlug, SelectType, TransformCollectionWithSelect, TypeWithVersion, Where } from 'payload';
+import type { DeepPartial } from 'ts-essentials';
+import type { AnyCollectionConfig, DbId } from '@/types';
+export declare class CollectionRepository<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug> {
+    protected readonly payload: BasePayload;
+    protected readonly collectionSlug: TSlug;
+    constructor(payload: BasePayload, collectionSlug: TSlug);
+    create<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(data: RequiredDataFromCollectionSlug<TSlug>, options?: CreateOptions<TConfig, TSlug, TSelect> & {
+        draft?: false;
+    }): Promise<SelectResult<TSlug, TSelect>>;
+    create<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(data: DraftDataFromCollectionSlug<TSlug>, options: CreateOptions<TConfig, TSlug, TSelect> & {
+        draft: true;
+    }): Promise<SelectResult<TSlug, TSelect>>;
+    duplicate<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(id: DbId, options?: DuplicateOptions<TConfig, TSlug, TSelect>): Promise<SelectResult<TSlug, TSelect>>;
+    find<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(options?: FindOptions<TConfig, TSlug, TSelect>): Promise<PaginatedSelectResult<TSlug, TSelect>>;
+    findById<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(id: DbId, options?: FindByIdOptions<TConfig, TSlug, TSelect>): Promise<SelectResult<TSlug, TSelect>>;
+    findByIds<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(ids: DbId[], options?: FindOptions<TConfig, TSlug, TSelect>): Promise<PaginatedSelectResult<TSlug, TSelect>>;
+    findDistinct<TField extends keyof DataFromCollectionSlug<TSlug> & string>(field: TField, options?: FindDistinctOptions): Promise<PaginatedDistinctDocs<Record<TField, DataFromCollectionSlug<TSlug>[TField]>>>;
+    findVersionById(id: string, options?: FindVersionByIdOptions): Promise<TypeWithVersion<DataFromCollectionSlug<TSlug>>>;
+    findVersions(options?: FindVersionsOptions): Promise<PaginatedDocs<TypeWithVersion<DataFromCollectionSlug<TSlug>>>>;
+    count(options?: CountOptions): CountResult;
+    countVersions(options?: CollectionCountVersionsOptions): CountVersionsResult;
+    update<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(where: Where, data: UpdateData<TSlug>, options?: UpdateOptions<TConfig, TSlug, TSelect>): Promise<BulkOperationResult<TSlug, TSelect>>;
+    updateById<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(id: DbId, data: UpdateData<TSlug>, options?: UpdateByIdOptions<TConfig, TSlug, TSelect>): Promise<SelectResult<TSlug, TSelect>>;
+    updateByIds<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(ids: DbId[], data: UpdateData<TSlug>, options?: UpdateOptions<TConfig, TSlug, TSelect>): Promise<BulkOperationResult<TSlug, TSelect>>;
+    delete<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(where: Where, options?: DeleteOptions<TConfig, TSlug, TSelect>): Promise<BulkOperationResult<TSlug, TSelect>>;
+    deleteById<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(id: DbId, options?: DeleteOptions<TConfig, TSlug, TSelect>): Promise<SelectResult<TSlug, TSelect>>;
+    deleteByIds<TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>>(ids: DbId[], options?: DeleteOptions<TConfig, TSlug, TSelect>): Promise<BulkOperationResult<TSlug, TSelect>>;
+}
+type TypedSelect<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug> = TConfig['collectionsSelect'][TSlug & string] & SelectType;
+type SelectResult<TSlug extends CollectionSlug, TSelect extends SelectType = SelectType> = TransformCollectionWithSelect<TSlug, TSelect>;
+type PaginatedSelectResult<TSlug extends CollectionSlug, TSelect extends SelectType = SelectType> = PaginatedDocs<SelectResult<TSlug, TSelect>>;
+type DraftDataFromCollectionSlug<TSlug extends CollectionSlug> = Partial<DataFromCollectionSlug<TSlug>>;
+type CreateOptions<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug, TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>> = Omit<Parameters<BasePayload['create']>[0], 'collection' | 'select' | 'data' | 'draft'> & {
+    select?: TSelect;
+};
+type DuplicateOptions<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug, TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>> = Omit<Parameters<BasePayload['duplicate']>[0], 'collection' | 'id' | 'select' | 'data'> & {
+    select?: TSelect;
+    data?: DeepPartial<RequiredDataFromCollectionSlug<TSlug>>;
+};
+type FindByIdOptions<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug, TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>> = Omit<Parameters<BasePayload['findByID']>[0], 'collection' | 'select' | 'id'> & {
+    select?: TSelect;
+};
+type FindOptions<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug, TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>> = Omit<Parameters<BasePayload['find']>[0], 'collection' | 'select' | 'where'> & {
+    select?: TSelect;
+};
+type FindDistinctOptions = Omit<Parameters<BasePayload['findDistinct']>[0], 'collection' | 'field'>;
+type FindVersionByIdOptions = Omit<Parameters<BasePayload['findVersionByID']>[0], 'collection' | 'id'>;
+type FindVersionsOptions = Omit<Parameters<BasePayload['findVersions']>[0], 'collection'>;
+type CountOptions = Omit<Parameters<BasePayload['count']>[0], 'collection'>;
+type CollectionCountVersionsOptions = Omit<Parameters<BasePayload['countVersions']>[0], 'collection'>;
+type CountResult = ReturnType<BasePayload['count']>;
+type CountVersionsResult = ReturnType<BasePayload['countVersions']>;
+type UpdateData<TSlug extends CollectionSlug> = DeepPartial<RequiredDataFromCollectionSlug<TSlug>>;
+type UpdateByIdOptions<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug, TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>> = Omit<Parameters<BasePayload['update']>[0], 'collection' | 'select' | 'id' | 'data'> & {
+    select?: TSelect;
+};
+type UpdateOptions<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug, TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>> = Omit<Parameters<BasePayload['update']>[0], 'collection' | 'select' | 'data' | 'where' | 'id'> & {
+    select?: TSelect;
+};
+type DeleteOptions<TConfig extends AnyCollectionConfig, TSlug extends CollectionSlug, TSelect extends TypedSelect<TConfig, TSlug> = TypedSelect<TConfig, TSlug>> = Omit<Parameters<BasePayload['delete']>[0], 'collection' | 'select' | 'where' | 'id'> & {
+    select?: TSelect;
+};
+export {};

package/dist/collection/CollectionRepository.js

@@ -0,0 +1,128 @@
+export class CollectionRepository {
+    payload;
+    collectionSlug;
+    constructor(payload, collectionSlug) {
+        this.payload = payload;
+        this.collectionSlug = collectionSlug;
+    }
+    async create(data, options) {
+        const { draft, ...createOptions } = options ?? {};
+        if (draft) {
+            return this.payload.create({
+                collection: this.collectionSlug,
+                data: data,
+                draft: true,
+                ...createOptions,
+            });
+        }
+        return this.payload.create({
+            collection: this.collectionSlug,
+            data: { ...data, _status: 'published' },
+            ...createOptions,
+        });
+    }
+    async duplicate(id, options) {
+        return this.payload.duplicate({
+            collection: this.collectionSlug,
+            id,
+            ...options,
+        });
+    }
+    async find(options) {
+        return this.payload.find({
+            collection: this.collectionSlug,
+            ...options,
+        });
+    }
+    async findById(id, options) {
+        return this.payload.findByID({
+            collection: this.collectionSlug,
+            id,
+            ...options,
+        });
+    }
+    async findByIds(ids, options) {
+        return this.payload.find({
+            collection: this.collectionSlug,
+            where: { id: { in: ids } },
+            ...options,
+        });
+    }
+    async findDistinct(field, options) {
+        return this.payload.findDistinct({
+            collection: this.collectionSlug,
+            field,
+            ...options,
+        });
+    }
+    async findVersionById(id, options) {
+        return this.payload.findVersionByID({
+            collection: this.collectionSlug,
+            id,
+            ...options,
+        });
+    }
+    async findVersions(options) {
+        return this.payload.findVersions({
+            collection: this.collectionSlug,
+            ...options,
+        });
+    }
+    async count(options) {
+        return this.payload.count({
+            collection: this.collectionSlug,
+            ...options,
+        });
+    }
+    async countVersions(options) {
+        return this.payload.countVersions({
+            collection: this.collectionSlug,
+            ...options,
+        });
+    }
+    async update(where, data, options) {
+        return this.payload.update({
+            collection: this.collectionSlug,
+            where,
+            data,
+            ...options,
+        });
+    }
+    async updateById(id, data, options) {
+        return this.payload.update({
+            collection: this.collectionSlug,
+            id,
+            data,
+            ...options,
+        });
+    }
+    async updateByIds(ids, data, options) {
+        return this.payload.update({
+            collection: this.collectionSlug,
+            where: { id: { in: ids } },
+            data,
+            ...options,
+        });
+    }
+    async delete(where, options) {
+        return this.payload.delete({
+            collection: this.collectionSlug,
+            where,
+            ...options,
+        });
+    }
+    async deleteById(id, options) {
+        return this.payload.delete({
+            collection: this.collectionSlug,
+            id,
+            ...options,
+        });
+    }
+    async deleteByIds(ids, options) {
+        return this.payload.delete({
+            collection: this.collectionSlug,
+            where: { id: { in: ids } },
+            ...options,
+        });
+    }
+}

package/dist/global/GlobalQuery.d.ts

@@ -0,0 +1,7 @@
+import type { BasePayload, GlobalSlug } from 'payload';
+import type { AnyGlobalConfig } from '@/types';
+import { GlobalRepository } from './GlobalRepository';
+export declare abstract class GlobalQuery<TConfig extends AnyGlobalConfig, TSlug extends GlobalSlug> {
+    protected readonly repository: GlobalRepository<TConfig, TSlug>;
+    protected constructor(payload: BasePayload, globalSlug: TSlug);
+}

package/dist/global/GlobalQuery.js

@@ -0,0 +1,7 @@
+import { GlobalRepository } from './GlobalRepository';
+export class GlobalQuery {
+    repository;
+    constructor(payload, globalSlug) {
+        this.repository = new GlobalRepository(payload, globalSlug);
+    }
+}

package/dist/global/GlobalRepository.d.ts

@@ -0,0 +1,27 @@
+import type { BasePayload, DataFromGlobalSlug, GlobalSlug, PaginatedDocs, SelectType, TransformGlobalWithSelect, TypeWithVersion } from 'payload';
+import type { DeepPartial } from 'ts-essentials';
+import type { AnyGlobalConfig, DbId } from '@/types';
+export declare class GlobalRepository<TConfig extends AnyGlobalConfig, TSlug extends GlobalSlug> {
+    protected readonly payload: BasePayload;
+    protected readonly globalSlug: TSlug;
+    constructor(payload: BasePayload, globalSlug: TSlug);
+    find<TSelect extends TypedGlobalSelect<TConfig, TSlug> = TypedGlobalSelect<TConfig, TSlug>>(options?: FindGlobalOptions<TConfig, TSlug, TSelect>): Promise<GlobalSelectResult<TSlug, TSelect>>;
+    findVersionById(id: DbId, options?: FindGlobalVersionByIdOptions): Promise<TypeWithVersion<DataFromGlobalSlug<TSlug>>>;
+    findVersions(options?: FindGlobalVersionsOptions): Promise<PaginatedDocs<TypeWithVersion<DataFromGlobalSlug<TSlug>>>>;
+    countVersions(options?: GlobalCountVersionsOptions): CountVersionsResult;
+    update<TSelect extends TypedGlobalSelect<TConfig, TSlug> = TypedGlobalSelect<TConfig, TSlug>>(data: UpdateGlobalData<TSlug>, options?: UpdateGlobalOptions<TConfig, TSlug, TSelect>): Promise<GlobalSelectResult<TSlug, TSelect>>;
+}
+type TypedGlobalSelect<TConfig extends AnyGlobalConfig, TSlug extends GlobalSlug> = TConfig['globalsSelect'][TSlug & string] & SelectType;
+type GlobalSelectResult<TSlug extends GlobalSlug, TSelect extends SelectType = SelectType> = TransformGlobalWithSelect<TSlug, TSelect>;
+type FindGlobalOptions<TConfig extends AnyGlobalConfig, TSlug extends GlobalSlug, TSelect extends TypedGlobalSelect<TConfig, TSlug> = TypedGlobalSelect<TConfig, TSlug>> = Omit<Parameters<BasePayload['findGlobal']>[0], 'slug' | 'select'> & {
+    select?: TSelect;
+};
+type FindGlobalVersionByIdOptions = Omit<Parameters<BasePayload['findGlobalVersionByID']>[0], 'slug' | 'id'>;
+type FindGlobalVersionsOptions = Omit<Parameters<BasePayload['findGlobalVersions']>[0], 'slug'>;
+type GlobalCountVersionsOptions = Omit<Parameters<BasePayload['countGlobalVersions']>[0], 'global'>;
+type CountVersionsResult = ReturnType<BasePayload['countGlobalVersions']>;
+type UpdateGlobalData<TSlug extends GlobalSlug> = DeepPartial<Omit<DataFromGlobalSlug<TSlug>, 'id'>>;
+type UpdateGlobalOptions<TConfig extends AnyGlobalConfig, TSlug extends GlobalSlug, TSelect extends TypedGlobalSelect<TConfig, TSlug> = TypedGlobalSelect<TConfig, TSlug>> = Omit<Parameters<BasePayload['updateGlobal']>[0], 'slug' | 'select' | 'data'> & {
+    select?: TSelect;
+};
+export {};

package/dist/global/GlobalRepository.js

@@ -0,0 +1,40 @@
+export class GlobalRepository {
+    payload;
+    globalSlug;
+    constructor(payload, globalSlug) {
+        this.payload = payload;
+        this.globalSlug = globalSlug;
+    }
+    async find(options) {
+        return this.payload.findGlobal({
+            slug: this.globalSlug,
+            ...options,
+        });
+    }
+    async findVersionById(id, options) {
+        return this.payload.findGlobalVersionByID({
+            slug: this.globalSlug,
+            id,
+            ...options,
+        });
+    }
+    async findVersions(options) {
+        return this.payload.findGlobalVersions({
+            slug: this.globalSlug,
+            ...options,
+        });
+    }
+    async countVersions(options) {
+        return this.payload.countGlobalVersions({
+            global: this.globalSlug,
+            ...options,
+        });
+    }
+    async update(data, options) {
+        return this.payload.updateGlobal({
+            slug: this.globalSlug,
+            data,
+            ...options,
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { CollectionQuery } from './collection/CollectionQuery';
+export { CollectionRepository } from './collection/CollectionRepository';
+export { GlobalQuery } from './global/GlobalQuery';
+export { GlobalRepository } from './global/GlobalRepository';
+export type { AnyCollectionConfig, AnyGlobalConfig, DbId } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { CollectionQuery } from './collection/CollectionQuery';
+export { CollectionRepository } from './collection/CollectionRepository';
+export { GlobalQuery } from './global/GlobalQuery';
+export { GlobalRepository } from './global/GlobalRepository';

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+export type DbId = number | string;
+export type AnyCollectionConfig = {
+    collectionsSelect: Record<string, unknown>;
+};
+export type AnyGlobalConfig = {
+    globalsSelect: Record<string, unknown>;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@bhofstaetter/payloadcms-repository",
+    "version": "0.1.0",
+    "description": "Opinionated repository and query object wrapper around Payload's local API.",
+    "license": "MIT",
+    "author": "Benedikt Hofstätter",
+    "homepage": "https://github.com/bhofstaetter/payloadcms-repository",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/bhofstaetter/payloadcms-repository.git"
+    },
+    "keywords": [
+        "payload",
+        "payloadcms",
+        "repository",
+        "repository-pattern",
+        "query-object",
+        "local api",
+        "data fetching"
+    ],
+    "type": "module",
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "typecheck": "tsc",
+        "lint": "biome check",
+        "lint:fix": "biome check --fix",
+        "prepublishOnly": "npm run lint && npm run typecheck && npm run build"
+    },
+    "peerDependencies": {
+        "payload": ">=3",
+        "ts-essentials": ">=10"
+    },
+    "devDependencies": {
+        "payload": "^3.78.0",
+        "@payloadcms/db-postgres": "^3.78.0",
+        "ts-essentials": "^10.0.0",
+        "typescript": "^5",
+        "@biomejs/biome": "2.4.4",
+        "@testcontainers/postgresql": "^11.11.0",
+        "vite-tsconfig-paths": "^6.1.1",
+        "vitest": "^4.0.18"
+    },
+    "engines": {
+        "node": ">=22.0.0"
+    }
+}