ampless 1.0.0-beta.58 → 1.0.0-beta.59

package/dist/index.d.ts

@@ -2001,6 +2001,57 @@ declare function resolvePluginSettings(manifest: PluginSettingsManifest | undefi
  */
 declare function extractFirstImageUrl(post: Post): string | null;
 
+/** How the scan ended. `null` = the fetcher was exhausted cleanly. */
+type BoundedScanTruncation = 'limit' | 'early' | null;
+interface BoundedScanResult<T> {
+    items: T[];
+    /**
+     * - `'limit'` — a `limit + 1`th item was actually fetched, so more
+     *   items exist beyond the returned `limit`; the extra item is
+     *   dropped from `items`.
+     * - `'early'` — one of the safety bounds tripped (`maxPages` reached
+     *   or the same `nextToken` came back twice), so the scan may have
+     *   stopped with more items unread.
+     * - `null` — the fetcher signalled exhaustion (no `nextToken`) at or
+     *   below `limit`.
+     */
+    truncated: BoundedScanTruncation;
+}
+interface BoundedScanOptions {
+    /**
+     * Target item count. The walk collects until it has `limit + 1`
+     * items (the extra confirms there really are more), the fetcher is
+     * exhausted, or a safety bound trips.
+     */
+    limit: number;
+    /** Max items requested per page (default 50). */
+    pageSizeCap?: number;
+    /** Hard cap on pages walked regardless of items collected (default 21). */
+    maxPages?: number;
+}
+interface BoundedScanPage<T> {
+    items: T[];
+    nextToken: string | null;
+}
+/**
+ * Walk `fetchPage` pages until we have `limit + 1` items (the extra
+ * item confirms there really are more items beyond `limit` — a present
+ * `nextToken` alone doesn't guarantee that, since a paginated backend
+ * can return a token alongside zero remaining items), the token is
+ * exhausted, or one of the two safety bounds below trips:
+ *
+ *  - `maxPages` pages walked without reaching either stop condition
+ *  - the same `nextToken` comes back twice (defends against a
+ *    misbehaving resolver looping forever)
+ *
+ * Returns at most `limit` items (the confirming `limit + 1`th item is
+ * dropped) alongside how the scan ended.
+ */
+declare function collectBounded<T>(fetchPage: (args: {
+    limit: number;
+    nextToken?: string;
+}) => Promise<BoundedScanPage<T>>, opts: BoundedScanOptions): Promise<BoundedScanResult<T>>;
+
 type PostListStatusFilter = 'all' | 'draft' | 'published';
 type PostListSort = 'updated-desc' | 'updated-asc' | 'published-desc' | 'published-asc' | 'title-asc' | 'title-desc';
 interface PostListFilterOptions {
@@ -2102,4 +2153,4 @@ declare function pickDefaultEntrypoint(files: readonly {
 
 declare const VERSION = "0.0.1";
 
-export { type AiConfig, type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFieldRenderer, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type HistoryConfig, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type ListPostHistoryOptions, type LocalizedString, MAX_BUNDLE_BYTES, type MarkdownEmbedMatch, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostListFilterOptions, type PostListSort, type PostListStatusFilter, type PostMetadata, type PostRevision, type PostRevisionConnection, type PostStatus, type PostSummary, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type PublicPostScriptDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, type SummaryListOptions, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TiptapNodeHtmlAdapters, type TiptapNodeMarkdownAdapters, type TiptapNodeToHtml, type TiptapNodeToMarkdown, type TiptapRenderNode, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, collectTags, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, filterSortPostSummaries, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPostHistory, listPostSummaries, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };
+export { type AiConfig, type AmplessEvent, type AmplessPlugin, type AuthContext, type BoundedScanOptions, type BoundedScanPage, type BoundedScanResult, type BoundedScanTruncation, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFieldRenderer, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type HistoryConfig, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type ListPostHistoryOptions, type LocalizedString, MAX_BUNDLE_BYTES, type MarkdownEmbedMatch, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostListFilterOptions, type PostListSort, type PostListStatusFilter, type PostMetadata, type PostRevision, type PostRevisionConnection, type PostStatus, type PostSummary, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type PublicPostScriptDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, type SummaryListOptions, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TiptapNodeHtmlAdapters, type TiptapNodeMarkdownAdapters, type TiptapNodeToHtml, type TiptapNodeToMarkdown, type TiptapRenderNode, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, collectBounded, collectTags, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, filterSortPostSummaries, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPostHistory, listPostSummaries, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

package/dist/index.js

@@ -501,6 +501,55 @@ function findHtmlImage(body) {
   return m ? m[1] : null;
 }
 
+// src/paging.ts
+var DEFAULT_PAGE_SIZE_CAP = 50;
+var DEFAULT_MAX_PAGES = 21;
+function requirePositiveInt(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(
+      `collectBounded: \`${name}\` must be a finite positive integer, received ${String(value)}`
+    );
+  }
+}
+async function collectBounded(fetchPage, opts) {
+  const limit = opts.limit;
+  const pageSizeCap = opts.pageSizeCap ?? DEFAULT_PAGE_SIZE_CAP;
+  const maxPages = opts.maxPages ?? DEFAULT_MAX_PAGES;
+  requirePositiveInt("limit", limit);
+  requirePositiveInt("pageSizeCap", pageSizeCap);
+  requirePositiveInt("maxPages", maxPages);
+  const items = [];
+  const seenTokens = /* @__PURE__ */ new Set();
+  let token;
+  let truncated = null;
+  for (let page = 0; page < maxPages; page++) {
+    const remaining = limit + 1 - items.length;
+    const pageLimit = Math.min(pageSizeCap, remaining);
+    const res = await fetchPage({ limit: pageLimit, nextToken: token });
+    items.push(...res.items);
+    if (items.length > limit) {
+      truncated = "limit";
+      break;
+    }
+    if (!res.nextToken) {
+      break;
+    }
+    if (seenTokens.has(res.nextToken)) {
+      truncated = "early";
+      break;
+    }
+    seenTokens.add(res.nextToken);
+    token = res.nextToken;
+    if (page === maxPages - 1) {
+      truncated = "early";
+    }
+  }
+  return {
+    items: truncated === "limit" ? items.slice(0, limit) : items,
+    truncated
+  };
+}
+
 // src/post-list-filter.ts
 function filterSortPostSummaries(rows, options = {}) {
   const query = options.query?.trim().toLowerCase() ?? "";
@@ -869,6 +918,7 @@ export {
   TEXT_EXTENSIONS,
   VERSION,
   bundlePrefix,
+  collectBounded,
   collectTags,
   createPost,
   decodeAwsJson,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-beta.58",
+  "version": "1.0.0-beta.59",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",