@enonic-types/lib-content 8.0.4-B2 → 8.1.0-B1

package/content.d.ts

@@ -190,6 +190,31 @@ export interface ContentsResult<Hit extends Content<unknown>, AggregationOutput
     aggregations: AggregationOutput;
     highlight?: Record<string, HighlightResult>;
 }
+/**
+ * A hit returned by {@link query} when `returns: 'ids'` is requested.
+ */
+export interface ContentIdHit {
+    id: string;
+    score: number;
+}
+/**
+ * A hit returned by {@link query} when `returns` names content fields, which are supplied in `fields`.
+ */
+export interface ContentFieldsHit {
+    id: string;
+    score: number;
+    fields?: Record<string, unknown>;
+}
+export interface ContentHitsResult<Hit, AggregationOutput extends Record<string, AggregationsResult> | undefined = undefined> {
+    total: number;
+    count: number;
+    hits: Hit[];
+    aggregations: AggregationOutput;
+    highlight?: Record<string, HighlightResult>;
+}
+/**
+ * @deprecated Use {@link QueryContentParams} with `parent` instead.
+ */
 export interface GetChildContentParams {
     key: string;
     start?: number;
@@ -201,6 +226,9 @@ export interface GetChildContentParams {
  *
  * @example-ref examples/content/getChildren.js
  *
+ * @deprecated Use {@link query} with `parent` instead. It accepts the same path or id, applies the same child order of the parent where
+ * `sort` is omitted, and additionally supports filters, content types, aggregations and highlighting.
+ *
  * @param {object} params JSON with the parameters.
  * @param {string} params.key Path or id to the parent content.
  * @param {number} [params.start=0] Start index (used for paging).
@@ -259,6 +287,9 @@ export declare function create<Data = Record<string, unknown>, Type extends stri
 export interface QueryContentParams<AggregationInput extends Aggregations = never> {
     start?: number;
     count?: number;
+    parent?: string;
+    recursive?: boolean;
+    returns?: 'contents' | 'ids' | string[];
     query?: QueryDsl | string;
     sort?: string | SortDsl | SortDsl[];
     filters?: Filter | Filter[];
@@ -270,10 +301,23 @@ export interface QueryContentParams<AggregationInput extends Aggregations = neve
  * This command queries content.
  *
  * @example-ref examples/content/query.js
+ * @example-ref examples/content/queryChildren.js
  *
  * @param {object} params JSON with the parameters.
  * @param {number} [params.start=0] Start index (used for paging).
  * @param {number} [params.count=10] Number of contents to fetch.
+ * @param {string} [params.parent] Path or id of a content to whose direct children the query is restricted. Where `sort` is not
+ * specified, the children are returned in the child order of the parent. A parent that does not exist matches nothing. A path is relative
+ * to the content root of the calling context; as the same API also serves the archive, an identical path denotes a different content
+ * depending on the context.
+ * @param {boolean} [params.recursive=false] Matches every descendant of `parent` rather than its direct children only. Requires
+ * `parent`. The child order of the parent is not applied to a subtree, since it orders siblings rather than levels, so specify `sort`
+ * where the order of a recursive result is significant.
+ * @param {string|string[]} [params.returns='contents'] Determines what each hit carries: `'contents'` for the whole content, which is
+ * the default, `'ids'` for id and score, or a list of content field names — `_name`, `_path`, `displayName`, `type`, `creator`,
+ * `modifier`, `createdTime`, `modifiedTime`, `owner`, `language` — supplied as `fields` on the hit. Any other name is an error, as is an
+ * empty list; request `'ids'` where no fields are required. Only fields a content exposes are available, so a hit returns exactly what
+ * the content would return. Every shape other than the default is answered without reading the contents at all.
  * @param {string|object} [params.query] Query expression.
  * @param {object|object[]} [params.filters] Filters to apply to query result
  * @param {string|object|object[]} [params.sort] Sorting expression.
@@ -283,6 +327,12 @@ export interface QueryContentParams<AggregationInput extends Aggregations = neve
  *
  * @returns {object} Result of query.
  */
+export declare function query<Hit extends Content<unknown> = Content, AggregationInput extends Aggregations = never>(params: QueryContentParams<AggregationInput> & {
+    returns: 'ids';
+}): ContentHitsResult<ContentIdHit, AggregationsToAggregationResults<AggregationInput>>;
+export declare function query<Hit extends Content<unknown> = Content, AggregationInput extends Aggregations = never>(params: QueryContentParams<AggregationInput> & {
+    returns: string[];
+}): ContentHitsResult<ContentFieldsHit, AggregationsToAggregationResults<AggregationInput>>;
 export declare function query<Hit extends Content<unknown> = Content, AggregationInput extends Aggregations = never>(params: QueryContentParams<AggregationInput>): ContentsResult<Hit, AggregationsToAggregationResults<AggregationInput>>;
 /**
  * @deprecated Use {@link UpdateContentParams} instead.
@@ -636,6 +686,12 @@ export declare function getPermissions(params: GetPermissionsParams): Permission
 export interface Icon {
     data: ByteSource;
     mimeType: string;
+    /**
+     * @deprecated Not a dependable measure of when the icon last changed, and unsuitable for cache
+     * invalidation. Icons are loaded from application resources, so this derives from a jar entry timestamp
+     * that build tools normalize to a constant for reproducibility, from the install time of the bundle
+     * providing the icon, or from the time the icon happened to be read.
+     */
     modifiedTime: string;
 }
 /**
@@ -648,11 +704,13 @@ export interface Icon {
  * @property {boolean} abstract Whether or not content of this type may be instantiated.
  * @property {boolean} final Whether or not it may be used as super type of other content types.
  * @property {boolean} allowChildContent Whether or not allow creating child items on content of this type.
- * @property {string} modifiedTime Modified time of the content type.
+ * @property {string} modifiedTime Modified time of the content type. Deprecated: derives from the build
+ * rather than from an edit whenever the content type comes from an application.
  * @property {object} [icon] Icon of the content type.
  * @property {object} [icon.data] Stream with the binary data for the icon.
  * @property {string} [icon.mimeType] Mime type of the icon image.
- * @property {string} [icon.modifiedTime] Modified time of the icon. May be used for caching.
+ * @property {string} [icon.modifiedTime] Modified time of the icon. Deprecated: derives from the build
+ * rather than from an edit to the icon, so it must not be used for caching.
  * @property {object[]} form Form schema represented as an array of form items: Input, ItemSet, Layout, OptionSet.
  * @property {object} config Custom schema configuration for the descriptor.
  */
@@ -664,6 +722,12 @@ export interface ContentType {
     abstract: boolean;
     final: boolean;
     allowChildContent: boolean;
+    /**
+     * @deprecated Not a dependable measure of when the content type last changed. Read from an application
+     * resource, this derives from a jar entry timestamp that build tools normalize to a constant for
+     * reproducibility; only a dynamic schema stored in a repository node carries a genuine time, and the two
+     * cannot be told apart here.
+     */
     modifiedTime: string;
     icon?: Icon;
     form: FormItem[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@enonic-types/lib-content",
-    "version": "8.0.4-B2",
+    "version": "8.1.0-B1",
     "description": "Type definitions for lib-content.",
     "types": "content.d.ts",
     "files": [
@@ -27,7 +27,7 @@
     },
     "homepage": "https://github.com/enonic/xp/tree/master#readme",
     "dependencies": {
-        "@enonic-types/core": "8.0.4-B2"
+        "@enonic-types/core": "8.1.0-B1"
     },
     "publishConfig": {
         "access": "public"