@tinacms/graphql 0.0.0-03bb823-20241101081633 → 0.0.0-059f480-20260324232913

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/ast-builder/index.d.ts

@@ -1,7 +1,7 @@
 /**
 
 */
-import { type FieldDefinitionNode, type ScalarTypeDefinitionNode, type InputValueDefinitionNode, type ObjectTypeDefinitionNode, type InterfaceTypeDefinitionNode, type NamedTypeNode, type UnionTypeDefinitionNode, type TypeDefinitionNode, type DirectiveNode, type EnumTypeDefinitionNode, type InputObjectTypeDefinitionNode, type DocumentNode, type FragmentDefinitionNode, type SelectionNode, type FieldNode, type InlineFragmentNode, type OperationDefinitionNode } from 'graphql';
+import { type FieldDefinitionNode, type ScalarTypeDefinitionNode, type InputValueDefinitionNode, type ObjectTypeDefinitionNode, type InterfaceTypeDefinitionNode, type NamedTypeNode, type UnionTypeDefinitionNode, type TypeDefinitionNode, type DirectiveNode, type EnumTypeDefinitionNode, type InputObjectTypeDefinitionNode, type DocumentNode, type FragmentDefinitionNode, type SelectionNode, type FieldNode, type InlineFragmentNode, type OperationDefinitionNode, type DefinitionNode } from 'graphql';
 export declare const SysFieldDefinition: {
     kind: "Field";
     name: {
@@ -153,9 +153,8 @@ export declare const astBuilder: {
     }) => DocumentNode;
 };
 type scalarNames = 'string' | 'boolean' | 'datetime' | 'image' | 'text' | 'number';
-export declare const extractInlineTypes: (item: TypeDefinitionNode | TypeDefinitionNode[]) => any;
+export declare const extractInlineTypes: (item: DefinitionNode | DefinitionNode[]) => DefinitionNode[];
 export declare function walk(maybeNode: TypeDefinitionNode, visited?: WeakSet<WeakKey>): IterableIterator<TypeDefinitionNode>;
-export declare function addNamespaceToSchema<T extends object | string>(maybeNode: T, namespace?: string[]): T;
 export declare const NAMER: {
     dataFilterTypeNameOn: (namespace: string[]) => string;
     dataFilterTypeName: (namespace: string[]) => string;

package/dist/build.d.ts

@@ -1,16 +1,14 @@
 /**
 
 */
+import { type DocumentNode } from 'graphql';
 import type { TinaSchema, Config } from '@tinacms/schema-tools';
 export declare const buildDotTinaFiles: ({ config, flags, buildSDK, }: {
     config: Config;
     flags?: string[];
     buildSDK?: boolean;
 }) => Promise<{
-    graphQLSchema: {
-        kind: "Document";
-        definitions: any;
-    };
+    graphQLSchema: DocumentNode;
     tinaSchema: TinaSchema;
     lookup: Record<string, import("./database").LookupMapType>;
     fragDoc: string;

package/dist/builder/index.d.ts

@@ -2,7 +2,7 @@
 
 */
 import { LookupMapType } from '../database';
-import type { ObjectTypeDefinitionNode, InlineFragmentNode, FieldDefinitionNode } from 'graphql';
+import type { FieldDefinitionNode, InlineFragmentNode, ObjectTypeDefinitionNode } from 'graphql';
 import type { Collection, Template } from '@tinacms/schema-tools';
 import { TinaSchema } from '@tinacms/schema-tools';
 export declare const createBuilder: ({ tinaSchema, }: {
@@ -177,7 +177,7 @@ export declare class Builder {
      * ```
      *
      * @public
-     * @param collection a Tina Cloud collection
+     * @param collection a TinaCloud collection
      */
     collectionFragment: (collection: Collection<true>) => Promise<import("graphql").FragmentDefinitionNode>;
     /**

package/dist/database/alias-utils.d.ts

@@ -1,3 +1,3 @@
-import { Template } from '@tinacms/schema-tools/src';
+import { Template } from '@tinacms/schema-tools';
 export declare const replaceNameOverrides: (template: Template, obj: any) => object;
 export declare const applyNameOverrides: (template: Template, obj: any) => object;

package/dist/database/bridge/filesystem.d.ts

@@ -3,10 +3,14 @@ import type { Bridge } from './index';
  * This is the bridge from whatever datasource we need for I/O.
  * The basic example here is for the filesystem, one is needed
  * for GitHub has well.
+ *
+ * @security All public methods validate their `filepath` / `pattern`
+ * argument via `assertWithinBase` before performing any I/O. If you add a
+ * new method that accepts a path, you MUST validate it the same way.
  */
 export declare class FilesystemBridge implements Bridge {
     rootPath: string;
-    outputPath?: string;
+    outputPath: string;
     constructor(rootPath: string, outputPath?: string);
     glob(pattern: string, extension: string): Promise<string[]>;
     delete(filepath: string): Promise<void>;

package/dist/database/bridge/index.d.ts

@@ -1,8 +1,36 @@
+/**
+ * I/O abstraction layer for reading/writing content files.
+ *
+ * @security **Path traversal (CWE-22):** All `filepath` and `pattern`
+ * parameters may originate from user input (e.g. GraphQL mutations or media
+ * API requests). Implementations MUST validate that resolved paths stay
+ * within their root/output directory before performing any filesystem
+ * operation. See `FilesystemBridge.assertWithinBase` and
+ * `IsomorphicBridge.assertWithinBase` for reference implementations.
+ *
+ * The recommended validation pattern is:
+ * ```ts
+ * const resolved = path.resolve(path.join(baseDir, filepath));
+ * if (!resolved.startsWith(path.resolve(baseDir) + path.sep)) {
+ *   throw new Error('Path traversal detected');
+ * }
+ * ```
+ *
+ * If you are adding a new Bridge implementation, add path traversal
+ * validation to every method that accepts a filepath from the caller.
+ */
 export interface Bridge {
     rootPath: string;
+    /**
+     * @param pattern   - Glob pattern prefix (untrusted — validate before use).
+     * @param extension - File extension to match.
+     */
     glob(pattern: string, extension: string): Promise<string[]>;
+    /** @param filepath - Relative path to delete (untrusted — validate before use). */
     delete(filepath: string): Promise<void>;
+    /** @param filepath - Relative path to read (untrusted — validate before use). */
     get(filepath: string): Promise<string>;
+    /** @param filepath - Relative path to write (untrusted — validate before use). */
     put(filepath: string, data: string): Promise<void>;
     /**
      * Optionally, the bridge can perform

package/dist/database/bridge/isomorphic.d.ts

@@ -18,6 +18,11 @@ export type IsomorphicGitBridgeOptions = {
 };
 /**
  * Bridge backed by isomorphic-git
+ *
+ * @security All public methods (glob, get, put, delete) validate their
+ * `filepath` / `pattern` argument via `assertWithinBase` before performing
+ * any git operations. If you add a new method that accepts a path, you
+ * MUST validate it the same way.
  */
 export declare class IsomorphicBridge implements Bridge {
     rootPath: string;

package/dist/database/datalayer.d.ts

@@ -2,7 +2,7 @@
 
 */
 import { BatchOp, Level } from './level';
-import { Collection } from '@tinacms/schema-tools';
+import type { Collection } from '@tinacms/schema-tools';
 export declare enum OP {
     EQ = "eq",
     GT = "gt",
@@ -49,6 +49,9 @@ export type FilterCondition = {
 };
 type StringEscaper = <T extends string | string[]>(input: T) => T;
 export declare const DEFAULT_COLLECTION_SORT_KEY = "__filepath__";
+export declare const REFS_COLLECTIONS_SORT_KEY = "__refs__";
+export declare const REFS_REFERENCE_FIELD = "__tina_ref__";
+export declare const REFS_PATH_FIELD = "__tina_ref_path__";
 export declare const DEFAULT_NUMERIC_LPAD = 4;
 export declare const coerceFilterChainOperands: (filterChain: (BinaryFilter | TernaryFilter)[], escapeString?: StringEscaper) => (BinaryFilter | TernaryFilter)[];
 export declare const makeFilter: ({ filterChain, }: {
@@ -71,6 +74,7 @@ export declare class FolderTreeBuilder {
 }
 export declare const makeFolderOpsForCollection: <T extends object>(folderTree: FolderTree, collection: Collection<true>, indexDefinitions: Record<string, IndexDefinition>, opType: "put" | "del", level: Level, escapeStr?: StringEscaper) => BatchOp[];
 export declare const makeIndexOpsForDocument: <T extends object>(filepath: string, collection: string | undefined, indexDefinitions: Record<string, IndexDefinition>, data: T, opType: "put" | "del", level: Level, escapeStr?: StringEscaper) => BatchOp[];
+export declare const makeRefOpsForDocument: <T extends object>(filepath: string, collection: string | undefined, references: Record<string, string[]> | undefined | null, data: T, opType: "put" | "del", level: Level) => BatchOp[];
 export declare const makeStringEscaper: (regex: RegExp, replacement: string) => StringEscaper;
 export declare const stringEscaper: StringEscaper;
 export {};

package/dist/database/index.d.ts

@@ -19,6 +19,7 @@ export interface DatabaseArgs {
     indexStatusCallback?: IndexStatusCallback;
     version?: boolean;
     namespace?: string;
+    levelBatchSize?: number;
 }
 export interface GitProvider {
     onPut: (key: string, value: string) => Promise<void>;
@@ -69,9 +70,11 @@ export declare class Database {
     indexStatusCallback: IndexStatusCallback | undefined;
     private readonly onPut;
     private readonly onDelete;
+    private readonly levelBatchSize;
     private tinaSchema;
     private contentNamespace;
     private collectionIndexDefinitions;
+    private collectionReferences;
     private _lookup;
     constructor(config: DatabaseArgs);
     private collectionForPath;
@@ -125,6 +128,7 @@ export declare class Database {
     getGraphQLSchemaFromBridge: () => Promise<DocumentNode>;
     getTinaSchema: (level?: Level) => Promise<Schema>;
     getSchema: (level?: Level, existingSchema?: Schema) => Promise<TinaSchema>;
+    getCollectionReferences: (level?: Level) => Promise<Record<string, Record<string, string[]>>>;
     getIndexDefinitions: (level?: Level) => Promise<Record<string, Record<string, IndexDefinition>>>;
     documentExists: (fullpath: unknown) => Promise<boolean>;
     query: (queryOptions: QueryOptions, hydrator: any) => Promise<{

package/dist/database/util.d.ts

@@ -1,19 +1,21 @@
-/**
-
-*/
+import { Collection, CollectionTemplateable, TinaSchema, normalizePath } from '@tinacms/schema-tools';
 import * as yup from 'yup';
-import { Collection, CollectionTemplateable, normalizePath, TinaSchema } from '@tinacms/schema-tools';
+import { ContentFormat, ContentFrontmatterFormat } from '@tinacms/schema-tools';
 import { Bridge } from './bridge';
 export { normalizePath };
-export declare const stringifyFile: (content: object, format: FormatType | string, keepTemplateKey: boolean, markdownParseConfig?: {
-    frontmatterFormat?: "toml" | "yaml" | "json";
+export declare const stringifyFile: (content: object, format: ContentFormat | string, // FIXME
+/** For non-polymorphic documents we don't need the template key */
+keepTemplateKey: boolean, markdownParseConfig?: {
+    frontmatterFormat?: ContentFrontmatterFormat;
     frontmatterDelimiters?: [string, string] | string;
+    yamlMaxLineWidth?: number;
 }) => string;
-export declare const parseFile: <T extends object>(content: string, format: FormatType | string, yupSchema: (args: typeof yup) => yup.ObjectSchema<any>, markdownParseConfig?: {
-    frontmatterFormat?: "toml" | "yaml" | "json";
+export declare const parseFile: <T extends object>(content: string, format: ContentFormat | string, // FIXME
+yupSchema: (args: typeof yup) => yup.ObjectSchema<any>, markdownParseConfig?: {
+    frontmatterFormat?: ContentFrontmatterFormat;
+    lineWidth?: number;
     frontmatterDelimiters?: [string, string] | string;
 }) => T;
-export type FormatType = 'json' | 'md' | 'mdx' | 'markdown';
 export declare const atob: (b64Encoded: string) => string;
 export declare const btoa: (string: string) => string;
 export declare const scanAllContent: (tinaSchema: TinaSchema, bridge: Bridge, callback: (collection: Collection<true>, contentPaths: string[]) => Promise<void>) => Promise<string[]>;

package/dist/index.d.ts

@@ -16,10 +16,7 @@ export { createSchema } from './schema/createSchema';
 export { buildDotTinaFiles };
 export type DummyType = unknown;
 export declare const buildSchema: (config: Config, flags?: string[]) => Promise<{
-    graphQLSchema: {
-        kind: "Document";
-        definitions: any;
-    };
+    graphQLSchema: import("graphql").DocumentNode;
     tinaSchema: import("@tinacms/schema-tools").TinaSchema;
     lookup: Record<string, import("./database").LookupMapType>;
     fragDoc: string;