@easy-cms/plugin-graphql 0.0.0-stage → 0.42.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +38 -2
- package/dist/index.d.ts +142 -0
- package/dist/index.js +1353 -0
- package/package.json +49 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kanawoot K.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,39 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @easy-cms/plugin-graphql
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A GraphQL API for Easy CMS: a type, queries and mutations for every collection and global, with the same access rules as REST, batched relationship loading and limits per request. Part of [Easy CMS](https://github.com/maritonx/easy-cms), the embedded, code-first headless CMS for Nuxt and Next.js.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @easy-cms/plugin-graphql
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Or `pnpm add`, `yarn add` or `bun add`.
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { graphqlPlugin } from '@easy-cms/plugin-graphql'
|
|
17
|
+
|
|
18
|
+
export default defineConfig({
|
|
19
|
+
// …
|
|
20
|
+
plugins: [graphqlPlugin()],
|
|
21
|
+
})
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
```graphql
|
|
25
|
+
{
|
|
26
|
+
posts(where: { title: { like: "hello" } }, sort: [createdAt_DESC], limit: 5) {
|
|
27
|
+
docs { id title category { name } }
|
|
28
|
+
totalDocs
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Send it to `/api/cms/graphql`, or open that address in a browser for GraphiQL (outside production).
|
|
34
|
+
|
|
35
|
+
## Links
|
|
36
|
+
|
|
37
|
+
[GraphQL](https://maritonx.github.io/easy-cms/guide/graphql) · [Documentation](https://maritonx.github.io/easy-cms/) ([ภาษาไทย](https://maritonx.github.io/easy-cms/th/)) · [GitHub](https://github.com/maritonx/easy-cms)
|
|
38
|
+
|
|
39
|
+
MIT License
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
import { EasyCMS, AuthUser, ID, RawDocument, ResolvedConfig, Plugin } from '@easy-cms/core';
|
|
2
|
+
import { GraphQLSchema, ExecutionResult, GraphQLScalarType, GraphQLObjectType, GraphQLFieldConfig } from 'graphql';
|
|
3
|
+
|
|
4
|
+
/** How documents are read: what the query asked for, kept with each document it returns. */
|
|
5
|
+
interface ReadArgs {
|
|
6
|
+
readonly locale?: string;
|
|
7
|
+
readonly fallbackLocale?: boolean;
|
|
8
|
+
readonly draft?: boolean;
|
|
9
|
+
}
|
|
10
|
+
/** What resolvers receive as their context, yours from `extend` included. */
|
|
11
|
+
interface GraphQLContext {
|
|
12
|
+
/** The Local API. Pass `{ user, overrideAccess: false }` to apply the reader's access rules. */
|
|
13
|
+
readonly cms: EasyCMS;
|
|
14
|
+
/** The logged-in user or API key, or `null`. */
|
|
15
|
+
readonly user: AuthUser | null;
|
|
16
|
+
/**
|
|
17
|
+
* One document by id, with the reader's access. Loads in the same tick are batched into one
|
|
18
|
+
* query per collection, and count towards `limits.documents`.
|
|
19
|
+
*/
|
|
20
|
+
load(collection: string, id: ID, read?: ReadArgs): Promise<RawDocument | null>;
|
|
21
|
+
/** Counts documents loaded another way towards `limits.documents`. */
|
|
22
|
+
count(documents: number): void;
|
|
23
|
+
}
|
|
24
|
+
interface ContextOptions {
|
|
25
|
+
/** Most documents one request may load. Default 2000. */
|
|
26
|
+
readonly documents?: number;
|
|
27
|
+
}
|
|
28
|
+
/** The context of one request: its user, its batched loads, its document count. */
|
|
29
|
+
declare function createContext(cms: EasyCMS, user: AuthUser | null, options?: ContextOptions): GraphQLContext;
|
|
30
|
+
|
|
31
|
+
interface RunOptions {
|
|
32
|
+
readonly schema: GraphQLSchema;
|
|
33
|
+
/** Most levels of fields in one operation. */
|
|
34
|
+
readonly depth: number;
|
|
35
|
+
/** Most documents one request loads. */
|
|
36
|
+
readonly documents: number;
|
|
37
|
+
/** Allow `__schema` and `__type`. */
|
|
38
|
+
readonly introspection: boolean;
|
|
39
|
+
/** Show GraphiQL to browsers. */
|
|
40
|
+
readonly graphiql: boolean;
|
|
41
|
+
}
|
|
42
|
+
interface GraphQLRequest {
|
|
43
|
+
readonly query: string;
|
|
44
|
+
readonly variables?: Record<string, unknown> | null;
|
|
45
|
+
readonly operationName?: string | null;
|
|
46
|
+
}
|
|
47
|
+
type Json = Record<string, unknown>;
|
|
48
|
+
/** Parses, checks and runs one request, for the user. */
|
|
49
|
+
declare function runGraphQL(cms: EasyCMS, user: AuthUser | null, input: GraphQLRequest, options: RunOptions, onlyQueries?: boolean): Promise<{
|
|
50
|
+
status: number;
|
|
51
|
+
body: ExecutionResult | Json;
|
|
52
|
+
allow?: string;
|
|
53
|
+
}>;
|
|
54
|
+
|
|
55
|
+
/** Names of a collection in the schema: its type, one document, and the list. */
|
|
56
|
+
interface CollectionNames {
|
|
57
|
+
/** The object type, e.g. `Post`. */
|
|
58
|
+
readonly type: string;
|
|
59
|
+
/** The query for one document, e.g. `post(id)`. */
|
|
60
|
+
readonly one: string;
|
|
61
|
+
/** The query for the list, e.g. `posts(where…)`. */
|
|
62
|
+
readonly many: string;
|
|
63
|
+
}
|
|
64
|
+
/** Names of a global in the schema: its type and its query. */
|
|
65
|
+
interface GlobalNames {
|
|
66
|
+
/** The object type, e.g. `Settings`. */
|
|
67
|
+
readonly type: string;
|
|
68
|
+
/** The query, e.g. `settings`. */
|
|
69
|
+
readonly one: string;
|
|
70
|
+
}
|
|
71
|
+
/** Names you choose, by collection or global slug. */
|
|
72
|
+
type NameOverrides = Readonly<Record<string, Partial<CollectionNames>>>;
|
|
73
|
+
|
|
74
|
+
/** Any JSON value: rich text documents, `json` fields, rows of blocks when writing. */
|
|
75
|
+
declare const JSONScalar: GraphQLScalarType<unknown, unknown>;
|
|
76
|
+
/** A date and time as an ISO 8601 string, as Easy CMS stores them. */
|
|
77
|
+
declare const DateTimeScalar: GraphQLScalarType<string, unknown>;
|
|
78
|
+
|
|
79
|
+
type FieldConfig = GraphQLFieldConfig<any, GraphQLContext, any>;
|
|
80
|
+
/** What `extend` adds to the schema, with graphql-js objects. */
|
|
81
|
+
interface GraphQLExtension {
|
|
82
|
+
/** More root queries, e.g. a search across collections. */
|
|
83
|
+
readonly query?: Readonly<Record<string, FieldConfig>>;
|
|
84
|
+
/** More root mutations. */
|
|
85
|
+
readonly mutation?: Readonly<Record<string, FieldConfig>>;
|
|
86
|
+
/** More fields on the generated types, by type name, e.g. `{ Post: { readingTime: … } }`. */
|
|
87
|
+
readonly fields?: Readonly<Record<string, Readonly<Record<string, FieldConfig>>>>;
|
|
88
|
+
}
|
|
89
|
+
interface ExtendArgs {
|
|
90
|
+
readonly config: ResolvedConfig;
|
|
91
|
+
/** The generated object types by name (`Post`, `Media`, `Settings`…), to return from resolvers. */
|
|
92
|
+
readonly types: Readonly<Record<string, GraphQLObjectType>>;
|
|
93
|
+
/** One of `types`; throws when there is no such type. */
|
|
94
|
+
type(name: string): GraphQLObjectType;
|
|
95
|
+
readonly scalars: {
|
|
96
|
+
readonly JSON: typeof JSONScalar;
|
|
97
|
+
readonly DateTime: typeof DateTimeScalar;
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
interface SchemaOptions {
|
|
101
|
+
/**
|
|
102
|
+
* Names you choose, by collection or global slug, e.g. `{ news: { one: 'newsItem' } }`.
|
|
103
|
+
* Default: from the slug, `categories` → type `Category`, queries `category` and `categories`.
|
|
104
|
+
*/
|
|
105
|
+
readonly names?: NameOverrides;
|
|
106
|
+
/** Collections and globals left out of the schema, by slug. */
|
|
107
|
+
readonly exclude?: readonly string[];
|
|
108
|
+
/** Your own queries, mutations and fields. */
|
|
109
|
+
readonly extend?: (args: ExtendArgs) => GraphQLExtension;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* The GraphQL schema of a config: a type per collection and global, queries to read them and
|
|
113
|
+
* mutations to change them through the Local API, with the reader's access rules. Resolvers
|
|
114
|
+
* expect a `GraphQLContext` (`createContext`).
|
|
115
|
+
*/
|
|
116
|
+
declare function buildGraphQLSchema(config: ResolvedConfig, options?: SchemaOptions): GraphQLSchema;
|
|
117
|
+
|
|
118
|
+
interface GraphQLPluginOptions extends SchemaOptions {
|
|
119
|
+
/** Path under the REST API. Default `/graphql`, so the endpoint is `/api/cms/graphql`. */
|
|
120
|
+
readonly path?: string;
|
|
121
|
+
readonly limits?: {
|
|
122
|
+
/** Most levels of fields in one query. Default 7. */
|
|
123
|
+
readonly depth?: number;
|
|
124
|
+
/** Most documents one request loads, relationships included. Default 2000. */
|
|
125
|
+
readonly documents?: number;
|
|
126
|
+
};
|
|
127
|
+
/** Let clients read the schema (`__schema`), as codegen and GraphiQL do. Default true. */
|
|
128
|
+
readonly introspection?: boolean;
|
|
129
|
+
/**
|
|
130
|
+
* GraphiQL for browsers that open the endpoint. Default: outside production
|
|
131
|
+
* (`NODE_ENV !== 'production'`).
|
|
132
|
+
*/
|
|
133
|
+
readonly graphiql?: boolean;
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* A GraphQL API at `/api/cms/graphql`: a type per collection and global, queries and mutations
|
|
137
|
+
* through the Local API with the same access rules as REST (sessions, Bearer tokens and API
|
|
138
|
+
* keys), batched relationship loading, and limits on depth and documents per request.
|
|
139
|
+
*/
|
|
140
|
+
declare function graphqlPlugin(options?: GraphQLPluginOptions): Plugin;
|
|
141
|
+
|
|
142
|
+
export { type CollectionNames, type ContextOptions, DateTimeScalar, type ExtendArgs, type GlobalNames, type GraphQLContext, type GraphQLExtension, type GraphQLPluginOptions, type GraphQLRequest, JSONScalar, type NameOverrides, type ReadArgs, type RunOptions, type SchemaOptions, buildGraphQLSchema, createContext, graphqlPlugin, runGraphQL };
|