@preprio/toolkit 0.5.0-rc.1 → 0.5.0-rc.3

package/dist/astro/index.d.cts

@@ -79,6 +79,17 @@ interface PreprMiddlewareOptions {
     version?: string;
 }
 
+/**
+ * What `normalizeQuery` accepts as the query: GraphQL source text, a parsed
+ * `DocumentNode` (from `graphql-tag`, Apollo or GraphQL Code Generator), or a
+ * string-like object such as codegen's `TypedDocumentString`.
+ */
+type QueryInput = string | {
+    kind: 'Document';
+} | {
+    toString(): string;
+};
+
 /**
  * Structural stand-in for Astro's `APIContext`, so this package needs no
  * build-time dependency on `astro`. Only the fields `onPreprRequest` uses.
@@ -87,6 +98,8 @@ interface AstroLikeContext {
     request: Request;
     /** Unused; typed loosely so passing the real Astro context still checks. */
     cookies?: unknown;
+    /** Per-request storage; carries the editor's unsaved changes in preview. */
+    locals?: object;
 }
 /** Astro middleware's `next()` — resolves to the `Response` from downstream. */
 type AstroNext = () => Promise<Response>;
@@ -116,5 +129,38 @@ declare function getPreprHeaders(headers: Headers): PreprHeaders;
  * its own.
  */
 declare function getToolbarProps(headers: Headers, token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
+interface AstroNormalizeQueryOptions {
+    /**
+     * Whether this render may show unsaved editor changes. Pass your preview
+     * flag, and never `true` on a production deployment. When false (the
+     * default) the result is returned untouched.
+     */
+    enabled?: boolean;
+    /** `Astro.locals`, where `onPreprRequest` leaves the editor's changes. */
+    locals?: object;
+    /** Which operation to use when the document holds more than one. */
+    operationName?: string;
+}
+/**
+ * Show the Prepr editor's unsaved changes on a server-rendered Astro page:
+ * pass the query and the result you fetched (with any client), and render
+ * what comes back.
+ *
+ * ```astro
+ * ---
+ * const data = await fetchFromPrepr(GetPageDocument, { slug });
+ * const page = normalizeQuery(GetPageDocument, data, {
+ *   enabled: preview,
+ *   locals: Astro.locals,
+ * });
+ * ---
+ * ```
+ *
+ * Needs `onPreprRequest` with `preview: true` in your middleware and
+ * `PreprToolbar.astro` on the page; the toolbar re-requests the page with
+ * the editor's changes while they type. Select `_id` on every item and
+ * component that should update.
+ */
+declare function normalizeQuery<T>(query: QueryInput, result: T, options?: AstroNormalizeQueryOptions): T;
 
-export { type AstroLikeContext, type AstroNext, type PreprMiddlewareOptions, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, onPreprRequest };
+export { type AstroLikeContext, type AstroNext, type AstroNormalizeQueryOptions, type PreprMiddlewareOptions, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, normalizeQuery, onPreprRequest };

package/dist/astro/index.d.ts

@@ -79,6 +79,17 @@ interface PreprMiddlewareOptions {
     version?: string;
 }
 
+/**
+ * What `normalizeQuery` accepts as the query: GraphQL source text, a parsed
+ * `DocumentNode` (from `graphql-tag`, Apollo or GraphQL Code Generator), or a
+ * string-like object such as codegen's `TypedDocumentString`.
+ */
+type QueryInput = string | {
+    kind: 'Document';
+} | {
+    toString(): string;
+};
+
 /**
  * Structural stand-in for Astro's `APIContext`, so this package needs no
  * build-time dependency on `astro`. Only the fields `onPreprRequest` uses.
@@ -87,6 +98,8 @@ interface AstroLikeContext {
     request: Request;
     /** Unused; typed loosely so passing the real Astro context still checks. */
     cookies?: unknown;
+    /** Per-request storage; carries the editor's unsaved changes in preview. */
+    locals?: object;
 }
 /** Astro middleware's `next()` — resolves to the `Response` from downstream. */
 type AstroNext = () => Promise<Response>;
@@ -116,5 +129,38 @@ declare function getPreprHeaders(headers: Headers): PreprHeaders;
  * its own.
  */
 declare function getToolbarProps(headers: Headers, token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
+interface AstroNormalizeQueryOptions {
+    /**
+     * Whether this render may show unsaved editor changes. Pass your preview
+     * flag, and never `true` on a production deployment. When false (the
+     * default) the result is returned untouched.
+     */
+    enabled?: boolean;
+    /** `Astro.locals`, where `onPreprRequest` leaves the editor's changes. */
+    locals?: object;
+    /** Which operation to use when the document holds more than one. */
+    operationName?: string;
+}
+/**
+ * Show the Prepr editor's unsaved changes on a server-rendered Astro page:
+ * pass the query and the result you fetched (with any client), and render
+ * what comes back.
+ *
+ * ```astro
+ * ---
+ * const data = await fetchFromPrepr(GetPageDocument, { slug });
+ * const page = normalizeQuery(GetPageDocument, data, {
+ *   enabled: preview,
+ *   locals: Astro.locals,
+ * });
+ * ---
+ * ```
+ *
+ * Needs `onPreprRequest` with `preview: true` in your middleware and
+ * `PreprToolbar.astro` on the page; the toolbar re-requests the page with
+ * the editor's changes while they type. Select `_id` on every item and
+ * component that should update.
+ */
+declare function normalizeQuery<T>(query: QueryInput, result: T, options?: AstroNormalizeQueryOptions): T;
 
-export { type AstroLikeContext, type AstroNext, type PreprMiddlewareOptions, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, onPreprRequest };
+export { type AstroLikeContext, type AstroNext, type AstroNormalizeQueryOptions, type PreprMiddlewareOptions, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, normalizeQuery, onPreprRequest };