@tinacms/graphql 1.5.16 → 1.5.17

package/README.md

@@ -0,0 +1,144 @@
+# @tinacms/graphql
+
+[Tina](https://tina.io) is a headless content management system with support for Markdown, MDX, JSON, YAML, and more. This package contains the logic required to turn a collection of folders and files into a database that can be queried using [GraphQL](https://tina.io/docs/graphql/queries).
+
+## Features
+
+- Query Markdown, MDX, JSON, YAML and more using GraphQL
+- Supports references between documents
+- Pre-generation of schema and query data to expedite website compilation
+
+## Getting Started
+
+The easiest way to use this package is as part of a broader TinaCMS site. The starter can be tested locally using:
+
+```
+npx create-tina-app@latest
+```
+
+Alternatively, you can directly install and use this package.
+
+### Install @tinacms/graphql
+
+```
+pnpm install
+pnpm add @tinacms/graphql
+```
+
+### Build your program
+
+The following example demonstrates how to use this package.
+
+```ts
+import { MemoryLevel } from 'memory-level';
+import {
+  Database,
+  FilesystemBridge,
+  buildSchema,
+  resolve
+} from '@tinacms/graphql';
+import {
+  Schema
+} from '@tinacms/schema-tools';
+
+const dir = 'content';
+
+// Where to source content from
+const bridge = new FilesystemBridge(dir);
+// Where to store the index data
+const indexStorage = new MemoryLevel<string, Record<string, string>>();
+
+// Create the schema/structure of the database
+const rawSchema: Schema = {
+  collections: [
+    {
+      name: 'post',
+      path: '', // Don't require content to be placed within a subdirectory
+      fields: [
+        {
+          type: 'string',
+          name: 'title',
+          isTitle: true,
+          required: true
+        }
+      ]
+    }
+  ]
+};
+const schema = await buildSchema({
+  schema: rawSchema,
+  build: {
+    publicFolder: '',
+    outputFolder: ''
+  }
+});
+
+// Create the object for editing and querying your repository
+const database = new Database({
+  bridge,
+  level: indexStorage,
+  tinaDirectory: 'tina'
+});
+
+// Generate the index data required to support querying
+await database.indexContent(schema)
+
+// Query the database and output the result
+// In this case, it will retrieve the title of the post 'in.md'
+const graphQLQuery = `
+query {
+  document(collection: "post", relativePath: "in.md") {
+    ...on Document {
+      _values,
+      _sys { title }
+    }
+  }
+}
+`
+const result = await resolve({
+  database,
+  query: graphQLQuery,
+  variables: {}
+});
+
+// Output the result
+console.log(JSON.stringify(result))
+```
+
+For the program to work:
+
+1. Install packages:
+    - [`@tinacms/schema-tools`](https://www.npmjs.com/package/@tinacms/schema-tools) 
+    - [`memory-level`](https://www.npmjs.com/package/memory-level)
+2. Add a file `content/in.md` of the following form:
+
+```md
+---
+title: Hello
+---
+```
+
+The output should be:
+
+```json
+{"data":{"document":{"_values":{"_collection":"post","_template":"post","title":"Hello"},"_sys":{"title":"Hello"}}}}
+```
+
+## Development
+
+The package is part of the [TinaCMS repository](https://github.com/tinacms/tinacms/).
+
+## Documentation
+
+Visit [Tina's documentation](https://tina.io/docs/) to learn more.
+
+## Questions?
+
+[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?url=https%3A%2F%2Ftinacms.org&text=I%20just%20checked%20out%20@tinacms%20on%20GitHub%20and%20it%20is%20sweet%21&hashtags=TinaCMS%2Cjamstack%2Cheadlesscms)
+[![Forum](https://shields.io/github/discussions/tinacms/tinacms)](https://github.com/tinacms/tinacms/discussions)
+
+Visit the [GitHub Discussions](https://github.com/tinacms/tinacms/discussions) or our [Community Discord](https://discord.com/invite/zumN63Ybpf) to ask questions, or look us up on on Twitter at [@tinacms](https://twitter.com/tinacms).
+
+## Contributing
+
+Please see our [./CONTRIBUTING.md](https://github.com/tinacms/tinacms/blob/main/CONTRIBUTING.md)

package/dist/index.js

@@ -3090,7 +3090,7 @@ var validateField = async (field) => {
 // package.json
 var package_default = {
   name: "@tinacms/graphql",
-  version: "1.5.16",
+  version: "1.5.17",
   main: "dist/index.js",
   module: "dist/index.mjs",
   typings: "dist/index.d.ts",
@@ -3116,7 +3116,6 @@ var package_default = {
     types: "pnpm tsc",
     build: "tinacms-scripts build",
     docs: "pnpm typedoc",
-    serve: "pnpm nodemon dist/server.js",
     test: "vitest run",
     "test-watch": "vitest"
   },
@@ -3171,7 +3170,6 @@ var package_default = {
     "@types/yup": "^0.29.14",
     "jest-file-snapshot": "^0.5.0",
     "memory-level": "^1.0.0",
-    nodemon: "3.1.4",
     typescript: "^5.7.3",
     vite: "^4.5.9",
     vitest: "^0.32.4",
@@ -7071,13 +7069,14 @@ var Database = class {
           documentPaths,
           async (collection, documentPaths2) => {
             if (collection && !collection.isDetached) {
-              await _indexContent(
-                this,
-                this.contentLevel,
-                documentPaths2,
+              await _indexContent({
+                database: this,
+                level: this.contentLevel,
+                documentPaths: documentPaths2,
                 enqueueOps,
-                collection
-              );
+                collection,
+                isPartialReindex: true
+              });
             }
           }
         );
@@ -7185,26 +7184,26 @@ var Database = class {
             );
             const doc = await level2.keys({ limit: 1 }).next();
             if (!doc) {
-              await _indexContent(
-                this,
-                level2,
-                contentPaths,
+              await _indexContent({
+                database: this,
+                level: level2,
+                documentPaths: contentPaths,
                 enqueueOps,
                 collection,
-                userFields.map((field) => [
+                passwordFields: userFields.map((field) => [
                   ...field.path,
                   field.passwordFieldName
                 ])
-              );
+              });
             }
           } else {
-            await _indexContent(
-              this,
+            await _indexContent({
+              database: this,
               level,
-              contentPaths,
+              documentPaths: contentPaths,
               enqueueOps,
               collection
-            );
+            });
           }
         }
       );
@@ -7343,7 +7342,15 @@ var hashPasswordValues = async (data, passwordFields) => Promise.all(
   )
 );
 var isGitKeep = (filepath, collection) => filepath.endsWith(`.gitkeep.${(collection == null ? void 0 : collection.format) || "md"}`);
-var _indexContent = async (database, level, documentPaths, enqueueOps, collection, passwordFields) => {
+var _indexContent = async ({
+  database,
+  level,
+  documentPaths,
+  enqueueOps,
+  collection,
+  passwordFields,
+  isPartialReindex
+}) => {
   var _a;
   let collectionIndexDefinitions;
   let collectionPath;
@@ -7385,40 +7392,42 @@ var _indexContent = async (database, level, documentPaths, enqueueOps, collectio
         normalizedPath,
         collectionPath || ""
       );
-      const item = await rootSublevel.get(normalizedPath);
-      if (item) {
-        await database.contentLevel.batch([
-          ...makeRefOpsForDocument(
-            normalizedPath,
-            collection == null ? void 0 : collection.name,
-            collectionReferences,
-            item,
-            "del",
-            level
-          ),
-          ...makeIndexOpsForDocument(
-            normalizedPath,
-            collection.name,
-            collectionIndexDefinitions,
-            item,
-            "del",
-            level
-          ),
-          // folder indices
-          ...makeIndexOpsForDocument(
-            normalizedPath,
-            `${collection.name}_${folderKey}`,
-            collectionIndexDefinitions,
-            item,
-            "del",
-            level
-          ),
-          {
-            type: "del",
-            key: normalizedPath,
-            sublevel: rootSublevel
-          }
-        ]);
+      if (isPartialReindex) {
+        const item = await rootSublevel.get(normalizedPath);
+        if (item) {
+          await database.contentLevel.batch([
+            ...makeRefOpsForDocument(
+              normalizedPath,
+              collection == null ? void 0 : collection.name,
+              collectionReferences,
+              item,
+              "del",
+              level
+            ),
+            ...makeIndexOpsForDocument(
+              normalizedPath,
+              collection.name,
+              collectionIndexDefinitions,
+              item,
+              "del",
+              level
+            ),
+            // folder indices
+            ...makeIndexOpsForDocument(
+              normalizedPath,
+              `${collection.name}_${folderKey}`,
+              collectionIndexDefinitions,
+              item,
+              "del",
+              level
+            ),
+            {
+              type: "del",
+              key: normalizedPath,
+              sublevel: rootSublevel
+            }
+          ]);
+        }
       }
       if (!isGitKeep(filepath, collection)) {
         await enqueueOps([

package/dist/index.mjs

@@ -3019,7 +3019,7 @@ var validateField = async (field) => {
 // package.json
 var package_default = {
   name: "@tinacms/graphql",
-  version: "1.5.16",
+  version: "1.5.17",
   main: "dist/index.js",
   module: "dist/index.mjs",
   typings: "dist/index.d.ts",
@@ -3045,7 +3045,6 @@ var package_default = {
     types: "pnpm tsc",
     build: "tinacms-scripts build",
     docs: "pnpm typedoc",
-    serve: "pnpm nodemon dist/server.js",
     test: "vitest run",
     "test-watch": "vitest"
   },
@@ -3100,7 +3099,6 @@ var package_default = {
     "@types/yup": "^0.29.14",
     "jest-file-snapshot": "^0.5.0",
     "memory-level": "^1.0.0",
-    nodemon: "3.1.4",
     typescript: "^5.7.3",
     vite: "^4.5.9",
     vitest: "^0.32.4",
@@ -6986,13 +6984,14 @@ var Database = class {
           documentPaths,
           async (collection, documentPaths2) => {
             if (collection && !collection.isDetached) {
-              await _indexContent(
-                this,
-                this.contentLevel,
-                documentPaths2,
+              await _indexContent({
+                database: this,
+                level: this.contentLevel,
+                documentPaths: documentPaths2,
                 enqueueOps,
-                collection
-              );
+                collection,
+                isPartialReindex: true
+              });
             }
           }
         );
@@ -7099,26 +7098,26 @@ var Database = class {
             );
             const doc = await level2.keys({ limit: 1 }).next();
             if (!doc) {
-              await _indexContent(
-                this,
-                level2,
-                contentPaths,
+              await _indexContent({
+                database: this,
+                level: level2,
+                documentPaths: contentPaths,
                 enqueueOps,
                 collection,
-                userFields.map((field) => [
+                passwordFields: userFields.map((field) => [
                   ...field.path,
                   field.passwordFieldName
                 ])
-              );
+              });
             }
           } else {
-            await _indexContent(
-              this,
+            await _indexContent({
+              database: this,
               level,
-              contentPaths,
+              documentPaths: contentPaths,
               enqueueOps,
               collection
-            );
+            });
           }
         }
       );
@@ -7257,7 +7256,15 @@ var hashPasswordValues = async (data, passwordFields) => Promise.all(
   )
 );
 var isGitKeep = (filepath, collection) => filepath.endsWith(`.gitkeep.${collection?.format || "md"}`);
-var _indexContent = async (database, level, documentPaths, enqueueOps, collection, passwordFields) => {
+var _indexContent = async ({
+  database,
+  level,
+  documentPaths,
+  enqueueOps,
+  collection,
+  passwordFields,
+  isPartialReindex
+}) => {
   let collectionIndexDefinitions;
   let collectionPath;
   if (collection) {
@@ -7298,40 +7305,42 @@ var _indexContent = async (database, level, documentPaths, enqueueOps, collectio
         normalizedPath,
         collectionPath || ""
       );
-      const item = await rootSublevel.get(normalizedPath);
-      if (item) {
-        await database.contentLevel.batch([
-          ...makeRefOpsForDocument(
-            normalizedPath,
-            collection?.name,
-            collectionReferences,
-            item,
-            "del",
-            level
-          ),
-          ...makeIndexOpsForDocument(
-            normalizedPath,
-            collection.name,
-            collectionIndexDefinitions,
-            item,
-            "del",
-            level
-          ),
-          // folder indices
-          ...makeIndexOpsForDocument(
-            normalizedPath,
-            `${collection.name}_${folderKey}`,
-            collectionIndexDefinitions,
-            item,
-            "del",
-            level
-          ),
-          {
-            type: "del",
-            key: normalizedPath,
-            sublevel: rootSublevel
-          }
-        ]);
+      if (isPartialReindex) {
+        const item = await rootSublevel.get(normalizedPath);
+        if (item) {
+          await database.contentLevel.batch([
+            ...makeRefOpsForDocument(
+              normalizedPath,
+              collection?.name,
+              collectionReferences,
+              item,
+              "del",
+              level
+            ),
+            ...makeIndexOpsForDocument(
+              normalizedPath,
+              collection.name,
+              collectionIndexDefinitions,
+              item,
+              "del",
+              level
+            ),
+            // folder indices
+            ...makeIndexOpsForDocument(
+              normalizedPath,
+              `${collection.name}_${folderKey}`,
+              collectionIndexDefinitions,
+              item,
+              "del",
+              level
+            ),
+            {
+              type: "del",
+              key: normalizedPath,
+              sublevel: rootSublevel
+            }
+          ]);
+        }
       }
       if (!isGitKeep(filepath, collection)) {
         await enqueueOps([

package/dist/schema/createSchema.d.ts

@@ -1,6 +1,3 @@
-/**
-
-*/
 import { TinaSchema, Schema } from '@tinacms/schema-tools';
 export declare const createSchema: ({ schema, flags, }: {
     schema: Schema;

package/dist/schema/validate.d.ts

@@ -1,6 +1,3 @@
-/**
-
-*/
 import { type Schema, type Collection } from '@tinacms/schema-tools';
 export declare const validateSchema: (schema: Schema) => Promise<{
     collections: Collection<true>[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinacms/graphql",
-  "version": "1.5.16",
+  "version": "1.5.17",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "typings": "dist/index.d.ts",
@@ -71,7 +71,6 @@
     "@types/yup": "^0.29.14",
     "jest-file-snapshot": "^0.5.0",
     "memory-level": "^1.0.0",
-    "nodemon": "3.1.4",
     "typescript": "^5.7.3",
     "vite": "^4.5.9",
     "vitest": "^0.32.4",
@@ -83,7 +82,6 @@
     "types": "pnpm tsc",
     "build": "tinacms-scripts build",
     "docs": "pnpm typedoc",
-    "serve": "pnpm nodemon dist/server.js",
     "test": "vitest run",
     "test-watch": "vitest"
   }

package/readme.md

@@ -1,194 +0,0 @@
-## Getting started
-
-There's a serve and watch command, which are separate for now:
-
-```sh
-// terminal 1
-cd packages/tina-graphql
-yarn watch
-
-// terminal 2
-cd packages/tina-graphql
-yarn serve
-```
-
-You can consume this from the `graphiql` app:
-
-```sh
-// terminal 3
-cd apps/graphiql
-yarn start
-```
-
-Note that this app doesn't use anything from the `client` package right now, it's just an interactive tool to see how things move from the graphql server into tina. That process has been improved in this package but will need to be merged back into the `client` package before this is usable.
-
-### Running queries
-
-By default the app will redirect to `project1` and display the default query generated from the `graphql-helpers` library - which consumes the fixtures from the `project1` folder the the `gql` package, any number of fixtures can be used if you want to add your own, just ensure the `server.ts` file knows about them.
-
-When you run the initial query, you should see the result along with the Tina sidebar toggle, this indicates that the Tina form has now been populated with the query values. If you change some values around and hit submit, the `onSubmit` function will populate the GraphiQL editor instead of sending it off to the server, you can play around with the mutation before sending it off if you'd like.
-
-### Tests
-
-The most valuable test right now is the `builder.spec.ts`, it's sort of an integration of all the field-level builders. There are also field-level build tests, but not resolvers ones just yet. If you're making changes to the builder just run `yarn test-watch` and hit `p` to provide a pattern, then type "builder", this will isolate that test and if it's passing you probably didn't break anything.
-
-## Architecture
-
-### Builder
-
-The builder service is responsible for building out the entire GraphQL schema for a given `.tina` config. This service can run at any time (but needs to be re-run on each schema change) and it's output is a GraphQL schema which can be stored in the schema definition language (SDL) as a string in a database record or as a `.graphql` file. At the top of the schema is a `document` query, this query returns the document, which can be one of any number of templates defined in the `.tina` config. From there, each field in the given template is used to build out the rest of the schema, so each template field is built by the `type` in it's definition
-
-#### Field-level builders
-
-Field-level builders take a field definition and produce 4 different GraphQL types:
-
-##### `field`
-
-Builds the type which fits into Tina's field definition shape:
-
-Given:
-
-```yaml
-name: Title
-label: title
-type: text
-```
-
-```js
-text.build.field({ cache, field });
-```
-
-Produces
-
-```graphql
-type TextField {
-  name: String
-  label: String
-  component: String
-  description: String
-}
-```
-
-##### `initialValue`
-
-Tina fields need an initial value when editing existing data. This builder is responsible for providing the shape of that value.
-
-For most fields this is the same value as `value` - but if you picture the schema as a "graph" - you can see how the "value" of a document reference (ie. a Post has an Author) is not helpful to Tina. Tina only cares about the stored document value of the reference (in this case `/path/to/author.md`) so it's the `initialValue`'s role to provide what makes sense to Tina, regardless of the schema's relationships.
-
-##### `value`
-
-The value of the field, it's the role of this function to provide the shape of the data we should expect for a fully resolved graph.
-
-For `block` fields, this looks like an array of different shapes, which means it's the `blocks.build.value` function's responsibility to return a `union` array.
-
-##### `input`
-
-When a mutation is made, the shape of this mutation needs to fit the shape create by this function.
-
-### Resolvers
-
-`resolvers` can be thought of as the runtime siblings to `builders`. While it's the job of builders to define the "graph", the resolvers are responsible for taking raw values (like those from a `.md` file) and shaping them so they fit the schema.
-
-#### Field-level resolvers
-
-Again, similar to field-level builders, most of the work for resolving the data is passed on to the appropriate field to handle. So if you have a document like so:
-
-```md
----
-title: Hello, World!
-author: /authors/homer.md
----
-```
-
-It's template definition might look like:
-
-```yaml
-label: Post
----
-fields:
-  - name: title
-    label: Title
-    type: text
-  - name: author
-    label: Author
-    type: select
-    config:
-      source:
-        type: pages
-        section: authors
-```
-
-The `text.resolver` object will be responsible for resolving the values related to `title`:
-
-##### `field`
-
-The `field` resolver provides the appropriate values for it's `field` builder counterpart. In the example above the `text.resolve.field` function would return:
-
-```json
-{
-  "name": "title",
-  "label": "Title",
-  "component": "text"
-}
-```
-
-This would then be passed on to Tina for rendering on the client.
-
-##### `initialValue`
-
-In the example above the `text.resolve.initialValue` would return "Hello, World!"
-
-For blocks we need to return the object along with a `_template` key, this is used downstream to disambiguate which template the value comes from.
-
-##### `value`
-
-In the example above the `text.resolve.value` would return "Hello, World!", and again, for document references this would return the entire document being referenced, which may or may not be used depending on the graph fields requested
-
-##### `input`
-
-Input resolvers don't do much (except in the case of blocks described later), since the GraphQL mutataion payload has all the necessary information, we just pass the value into these resolvers as a runtime type-check. In the future, this is where field-level validations can take place.
-
-**Caveats with `blocks`**: `blocks` values are an array of unlike objects, meaning in order to enforce type-safe requests coming into the server, we need to use a somewhat awkward pattern ([read more about the trade-offs here](https://github.com/graphql/graphql-spec/blob/master/rfcs/InputUnion.md#-5-one-of-tagged-union)) which we sort of need to rearrange once it hits the server.
-
-## Architecture Diagram
-
-<iframe style="border:none" width="700" height="350" src="https://whimsical.com/embed/Kh28ULaAYKPRpeCLm3VG63@2Ux7TurymMtzhxz2sLxX"></iframe>
-
-## Caveats
-
-### Why do we use `GraphQLUnion` instead of `GraphQLInterface` for fields?
-
-Since `component`, `label`, & `name` are common across all fields, we'd only use a fragment to gather what's unique to that field type, so field definitions using an interface would allow our queries to look like this:
-
-```graphql
-fields {
-  component
-  label
-  name
-  ...on SelectField {
-    options
-  }
-}
-```
-
-Instead, we use a union - which requires us to load each key inside it's respective fragment:
-
-```graphql
-fields {
-  ... on TextareaField {
-    name
-    label
-    component
-  }
-  ... on SelectField {
-    name
-    label
-    component
-    options
-  }
-}
-```
-
-A GraphQL interface allows you to define a heterogeneous set of types, which have some fields in common. This is a textbook usecase for interfaces, and it's something that could change in the future. But the current reason we're using unions is because unions are exhaustive, and they allow us to scope down the possible field types for a given set of fields.
-
-An interface would be too broad for our needs, a collection of fields should only contain the types which are possible for that given template config. So while an `interface` would allow us to present **all** possible field types, a `union` gives us the ability to scope down the field list to only allow what the template defines. Using `unions` forces us to be explicit about that in a way that's clear (note: it may be possible to do this with interfaces but there would end up being an interface for each collection of possible fields - making the `interface` term somewhat misleading). Using unions also allows our auto-querybuilder to know that they have populated all possible types of a field, something that seems like it might be more difficult with interfaces.