@aws-amplify/datastore 3.14.4 → 3.14.5-unstable.4

package/lib/predicates/next.d.ts

@@ -0,0 +1,301 @@
+import { Scalar, PersistentModel, ModelMeta, AllOperators, PredicateFieldType, ModelPredicate as StoragePredicate } from '../types';
+import { ExclusiveStorage as StorageAdapter } from '../storage/storage';
+declare type MatchableTypes = string | string[] | number | number[] | boolean | boolean[];
+declare type AllFieldOperators = keyof AllOperators;
+declare type NonNeverKeys<T> = {
+    [K in keyof T]: T[K] extends never ? never : K;
+}[keyof T];
+declare type WithoutNevers<T> = Pick<T, NonNeverKeys<T>>;
+/**
+ * A function that accepts a RecursiveModelPrecicate<T>, which it must use to
+ * return a final condition.
+ *
+ * This is used in `DataStore.query()`, `DataStore.observe()`, and
+ * `DataStore.observeQuery()` as the second argument. E.g.,
+ *
+ * ```
+ * DataStore.query(MyModel, model => model.field.eq('some value'))
+ * ```
+ *
+ * More complex queries should also be supported. E.g.,
+ *
+ * ```
+ * DataStore.query(MyModel, model => model.and(m => [
+ *   m.relatedEntity.or(relative => [
+ *     relative.relativeField.eq('whatever'),
+ *     relative.relativeField.eq('whatever else')
+ *   ]),
+ *   m.myModelField.ne('something')
+ * ]))
+ * ```
+ */
+export declare type RecursiveModelPredicateExtender<RT extends PersistentModel> = (lambda: RecursiveModelPredicate<RT>) => PredicateInternalsKey;
+export declare type RecursiveModelPredicateAggregateExtender<RT extends PersistentModel> = (lambda: RecursiveModelPredicate<RT>) => PredicateInternalsKey[];
+declare type RecursiveModelPredicateOperator<RT extends PersistentModel> = (predicates: RecursiveModelPredicateAggregateExtender<RT>) => PredicateInternalsKey;
+declare type RecursiveModelPredicateNegation<RT extends PersistentModel> = (predicate: RecursiveModelPredicateExtender<RT>) => PredicateInternalsKey;
+export declare type RecursiveModelPredicate<RT extends PersistentModel> = {
+    [K in keyof RT]-?: PredicateFieldType<RT[K]> extends PersistentModel ? RecursiveModelPredicate<PredicateFieldType<RT[K]>> : ValuePredicate<RT, RT[K]>;
+} & {
+    or: RecursiveModelPredicateOperator<RT>;
+    and: RecursiveModelPredicateOperator<RT>;
+    not: RecursiveModelPredicateNegation<RT>;
+} & PredicateInternalsKey;
+/**
+ * A function that accepts a ModelPrecicate<T>, which it must use to return a
+ * final condition.
+ *
+ * This is used as predicates in `DataStore.save()`, `DataStore.delete()`, and
+ * DataStore sync expressions.
+ *
+ * ```
+ * DataStore.save(record, model => model.field.eq('some value'))
+ * ```
+ *
+ * Logical operators are supported. But, condtiions are related records are
+ * NOT supported. E.g.,
+ *
+ * ```
+ * DataStore.delete(record, model => model.or(m => [
+ * 	m.field.eq('whatever'),
+ * 	m.field.eq('whatever else')
+ * ]))
+ * ```
+ */
+export declare type ModelPredicateExtender<RT extends PersistentModel> = (lambda: ModelPredicate<RT>) => PredicateInternalsKey;
+export declare type ModelPredicateAggregateExtender<RT extends PersistentModel> = (lambda: ModelPredicate<RT>) => PredicateInternalsKey[];
+declare type ValuePredicate<RT extends PersistentModel, MT extends MatchableTypes> = {
+    [K in AllFieldOperators]: K extends 'between' ? (inclusiveLowerBound: Scalar<MT>, inclusiveUpperBound: Scalar<MT>) => PredicateInternalsKey : (operand: Scalar<MT>) => PredicateInternalsKey;
+};
+export declare type ModelPredicate<RT extends PersistentModel> = WithoutNevers<{
+    [K in keyof RT]-?: PredicateFieldType<RT[K]> extends PersistentModel ? never : ValuePredicate<RT, RT[K]>;
+}> & {
+    or: ModelPredicateOperator<RT>;
+    and: ModelPredicateOperator<RT>;
+    not: ModelPredicateNegation<RT>;
+} & PredicateInternalsKey;
+declare type ModelPredicateOperator<RT extends PersistentModel> = (predicates: ModelPredicateAggregateExtender<RT>) => PredicateInternalsKey;
+declare type ModelPredicateNegation<RT extends PersistentModel> = (predicate: ModelPredicateExtender<RT>) => PredicateInternalsKey;
+declare type GroupOperator = 'and' | 'or' | 'not';
+declare type UntypedCondition = {
+    fetch: (storage: StorageAdapter) => Promise<Record<string, any>[]>;
+    matches: (item: Record<string, any>) => Promise<boolean>;
+    copy(extract: GroupCondition): [UntypedCondition, GroupCondition | undefined];
+    toAST(): any;
+};
+/**
+ * A pointer used by DataStore internally to lookup predicate details
+ * that should not be exposed on public customer interfaces.
+ */
+export declare class PredicateInternalsKey {
+    private __isPredicateInternalsKeySentinel;
+}
+/**
+ * Takes a key object from `registerPredicateInternals()` to fetch an internal
+ * `GroupCondition` object, which can then be used to query storage or
+ * test/match objects.
+ *
+ * This indirection exists to hide `GroupCondition` from public interfaces, since
+ * `GroupCondition` contains extra methods and properties that public callers
+ * should not use.
+ *
+ * @param key A key object previously returned by `registerPredicateInternals()`
+ */
+export declare const internals: (key: any) => GroupCondition;
+/**
+ * A condition that can operate against a single "primitive" field of a model or item.
+ * @member field The field of *some record* to test against.
+ * @member operator The equality or comparison operator to use.
+ * @member operands The operands for the equality/comparison check.
+ */
+export declare class FieldCondition {
+    field: string;
+    operator: string;
+    operands: string[];
+    constructor(field: string, operator: string, operands: string[]);
+    /**
+     * Creates a copy of self.
+     * @param extract Not used. Present only to fulfill the `UntypedCondition` interface.
+     * @returns A new, identitical `FieldCondition`.
+     */
+    copy(extract: GroupCondition): [FieldCondition, GroupCondition | undefined];
+    toAST(): {
+        [x: string]: {
+            [x: string]: string | string[];
+        };
+    };
+    /**
+     * Not implemented. Not needed. GroupCondition instead consumes FieldConditions and
+     * transforms them into legacy predicates. (*For now.*)
+     * @param storage N/A. If ever implemented, the storage adapter to query.
+     * @returns N/A. If ever implemented, return items from `storage` that match.
+     */
+    fetch(storage: StorageAdapter): Promise<Record<string, any>[]>;
+    /**
+     * Determins whether a given item matches the expressed condition.
+     * @param item The item to test.
+     * @returns `Promise<boolean>`, `true` if matches; `false` otherwise.
+     */
+    matches(item: Record<string, any>): Promise<boolean>;
+    /**
+     * Checks `this.operands` for compatibility with `this.operator`.
+     */
+    validate(): void;
+}
+/**
+ * A set of sub-conditions to operate against a model, optionally scoped to
+ * a specific field, combined with the given operator (one of `and`, `or`, or `not`).
+ * @member groupId Used to distinguish between GroupCondition instances for
+ * debugging and troublehsooting.
+ * @member model A metadata object that tells GroupCondition what to query and how.
+ * @member field The field on the model that the sub-conditions apply to.
+ * @member operator How to group child conditions together.
+ * @member operands The child conditions.
+ */
+export declare class GroupCondition {
+    /**
+     * The `ModelMeta` of the model to query and/or filter against.
+     * Expected to contain:
+     *
+     * ```js
+     * {
+     * 	builder: ModelConstructor,
+     * 	schema: SchemaModel,
+     * 	pkField: string[]
+     * }
+     * ```
+     */
+    model: ModelMeta<any>;
+    /**
+     * If populated, this group specifices a condition on a relationship.
+     *
+     * If `field` does *not* point to a related model, that's an error. It
+     * could indicate that the `GroupCondition` was instantiated with bad
+     * data, or that the model metadata is incorrect.
+     */
+    field: string | undefined;
+    /**
+     * If a `field` is given, whether the relationship is a `HAS_ONE`,
+     * 'HAS_MANY`, or `BELONGS_TO`.
+     *
+     * TODO: Remove this and replace with derivation using
+     * `ModelRelationship.from(this.model, this.field).relationship`;
+     */
+    relationshipType: string | undefined;
+    /**
+     *
+     */
+    operator: GroupOperator;
+    /**
+     *
+     */
+    operands: UntypedCondition[];
+    groupId: string;
+    constructor(
+    /**
+     * The `ModelMeta` of the model to query and/or filter against.
+     * Expected to contain:
+     *
+     * ```js
+     * {
+     * 	builder: ModelConstructor,
+     * 	schema: SchemaModel,
+     * 	pkField: string[]
+     * }
+     * ```
+     */
+    model: ModelMeta<any>, 
+    /**
+     * If populated, this group specifices a condition on a relationship.
+     *
+     * If `field` does *not* point to a related model, that's an error. It
+     * could indicate that the `GroupCondition` was instantiated with bad
+     * data, or that the model metadata is incorrect.
+     */
+    field: string | undefined, 
+    /**
+     * If a `field` is given, whether the relationship is a `HAS_ONE`,
+     * 'HAS_MANY`, or `BELONGS_TO`.
+     *
+     * TODO: Remove this and replace with derivation using
+     * `ModelRelationship.from(this.model, this.field).relationship`;
+     */
+    relationshipType: string | undefined, 
+    /**
+     *
+     */
+    operator: GroupOperator, 
+    /**
+     *
+     */
+    operands: UntypedCondition[]);
+    /**
+     * Returns a copy of a GroupCondition, which also returns the copy of a
+     * given reference node to "extract".
+     * @param extract A node of interest. Its copy will *also* be returned if the node exists.
+     * @returns [The full copy, the copy of `extract` | undefined]
+     */
+    copy(extract: GroupCondition): [GroupCondition, GroupCondition | undefined];
+    /**
+     * Fetches matching records from a given storage adapter using legacy predicates (for now).
+     * @param storage The storage adapter this predicate will query against.
+     * @param breadcrumb For debugging/troubleshooting. A list of the `groupId`'s this
+     * GroupdCondition.fetch is nested within.
+     * @param negate Whether to match on the `NOT` of `this`.
+     * @returns An `Promise` of `any[]` from `storage` matching the child conditions.
+     */
+    fetch(storage: StorageAdapter, breadcrumb?: string[], negate?: boolean): Promise<Record<string, any>[]>;
+    /**
+     * Determines whether a single item matches the conditions of `this`.
+     * When checking the target `item`'s properties, each property will be `await`'d
+     * to ensure lazy-loading is respected where applicable.
+     * @param item The item to match against.
+     * @param ignoreFieldName Tells `match()` that the field name has already been dereferenced.
+     * (Used for iterating over children on HAS_MANY checks.)
+     * @returns A boolean (promise): `true` if matched, `false` otherwise.
+     */
+    matches(item: Record<string, any>, ignoreFieldName?: boolean): Promise<boolean>;
+    /**
+     * Tranfsorm to a AppSync GraphQL compatible AST.
+     * (Does not support filtering in nested types.)
+     */
+    toAST(): {
+        [x: string]: any[];
+    };
+    toStoragePredicate<T>(baseCondition?: StoragePredicate<T>): StoragePredicate<T>;
+}
+/**
+ * Creates a "seed" predicate that can be used to build an executable condition.
+ * This is used in `query()`, for example, to seed customer- E.g.,
+ *
+ * ```
+ * const p = predicateFor({builder: modelConstructor, schema: modelSchema, pkField: string[]});
+ * p.and(child => [
+ *   child.field.eq('whatever'),
+ *   child.childModel.childField.eq('whatever else'),
+ *   child.childModel.or(child => [
+ *     child.otherField.contains('x'),
+ *     child.otherField.contains('y'),
+ *     child.otherField.contains('z'),
+ *   ])
+ * ])
+ * ```
+ *
+ * `predicateFor()` returns objecst with recursive getters. To facilitate this,
+ * a `query` and `tail` can be provided to "accumulate" nested conditions.
+ *
+ * TODO: the sortof-immutable algorithm was originally done to support legacy style
+ * predicate branching (`p => p.x.eq(value).y.eq(value)`). i'm not sure this is
+ * necessary or beneficial at this point, since we decided that each field condition
+ * must flly terminate a branch. is the strong mutation barrier between chain links
+ * still necessary or helpful?
+ *
+ * @param ModelType The ModelMeta used to build child properties.
+ * @param field Scopes the query branch to a field.
+ * @param query A base query to build on. Omit to start a new query.
+ * @param tail The point in an existing `query` to attach new conditions to.
+ * @returns A ModelPredicate (builder) that customers can create queries with.
+ * (As shown in function description.)
+ */
+export declare function recursivePredicateFor<T extends PersistentModel>(ModelType: ModelMeta<T>, allowRecursion?: boolean, field?: string, query?: GroupCondition, tail?: GroupCondition): RecursiveModelPredicate<T> & PredicateInternalsKey;
+export declare function predicateFor<T extends PersistentModel>(ModelType: ModelMeta<T>): ModelPredicate<T> & PredicateInternalsKey;
+export {};