@servicenow/glide 26.0.1 → 27.0.2

package/src/types/GlideQuery.d.ts

@@ -0,0 +1,645 @@
+import { GlideRecord } from "./GlideRecord";
+
+/**
+ * TypeScript definitions for ServiceNow GlideQuery
+ */
+
+/**
+ * Represents a single record returned from a query
+ */
+interface GlideQueryRecord {
+  [field: string]: any;
+}
+
+/**
+ * Optional container that may or may not contain a value
+ */
+interface Optional<T> {
+  /**
+   * Returns the value if present, otherwise returns the provided default value
+   */
+  orElse(defaultValue: T): T;
+  
+  /**
+   * Returns the value if present
+   */
+  get(): T | undefined;
+  
+  /**
+   * Returns true if a value is present
+   */
+  isPresent(): boolean;
+  
+  /**
+   * Executes the provided function if a value is present
+   */
+  ifPresent(consumer: (value: T) => void): void;
+}
+
+/**
+ * Stream interface for processing query results
+ */
+interface Stream<T> {
+  /**
+   * Converts the stream to an array
+   */
+  toArray(maxSize?: number): T[];
+  
+  /**
+   * Executes the provided function for each element
+   */
+  forEach(callback: (item: T) => void): void;
+  
+  /**
+   * Filters elements based on a predicate
+   */
+  filter(predicate: (item: T) => boolean): Stream<T>;
+  
+  /**
+   * Maps elements to a new form
+   */
+  map<R>(mapper: (item: T) => R): Stream<R>;
+  
+  /**
+   * Reduces the stream to a single value
+   */
+  reduce<R>(accumulator: (acc: R, item: T) => R, initialValue: R): R;
+  
+  /**
+   * Returns the first element as an Optional
+   */
+  findFirst(): Optional<T>;
+  
+  /**
+   * Limits the stream to the specified number of elements
+   */
+  limit(maxSize: number): Stream<T>;
+  
+  /**
+   * Returns true if any element matches the predicate
+   */
+  anyMatch(predicate: (item: T) => boolean): boolean;
+  
+  /**
+   * Returns true if all elements match the predicate
+   */
+  allMatch(predicate: (item: T) => boolean): boolean;
+  
+  /**
+   * Returns true if no elements match the predicate
+   */
+  noneMatch(predicate: (item: T) => boolean): boolean;
+}
+
+/**
+ * Valid comparison operators for where clauses
+ */
+type ComparisonOperator = '=' | '!=' | '>' | '>=' | '<' | '<=';
+
+/**
+ * Valid array operators
+ */
+type ArrayOperator = 'IN' | 'NOT IN' | 'BETWEEN';
+
+/**
+ * Valid string operators
+ */
+type StringOperator = 
+  | 'STARTSWITH' 
+  | 'ENDSWITH' 
+  | 'CONTAINS' 
+  | 'DOES NOT CONTAIN' 
+  | 'INSTANCEOF'
+  | 'SAMEAS'
+  | 'NSAMEAS'
+  | 'GT_FIELD'
+  | 'LT_FIELD'
+  | 'GT_OR_EQUALS_FIELD'
+  | 'LT_OR_EQUALS_FIELD'
+  | 'DYNAMIC'
+  | 'EMPTYSTRING'
+  | 'ANYTHING'
+  | 'LIKE'
+  | 'NOT LIKE'
+  | 'ON';
+
+/**
+ * All valid operators
+ */
+type WhereOperator = ComparisonOperator | ArrayOperator | StringOperator;
+
+/**
+ * Valid aggregate function types
+ */
+type AggregateType = 'sum' | 'avg' | 'min' | 'max' | 'count';
+
+/**
+ * Field flags that can be appended to field names
+ */
+type FieldFlag = 'DISPLAY' | 'CURRENCY_CODE' | 'CURRENCY_DISPLAY' | 'CURRENCY_STRING';
+
+/**
+ * Field name with optional flag (e.g., 'company$DISPLAY')
+ */
+type FieldWithFlag = string;
+
+/**
+ * Key-value object for record data
+ */
+interface KeyValues {
+  [key: string]: any;
+}
+
+/**
+ * Options for GlideQuery constructor
+ */
+interface GlideQueryOptions {
+  scope?: string;
+}
+
+/**
+ * Result of updateMultiple operation
+ */
+interface UpdateMultipleResult {
+  rowCount: number;
+}
+
+/**
+ * Main GlideQuery class used to build and execute queries.
+ * 
+ * @example
+ * var query = new GlideQuery('sys_user');
+ */
+export declare class GlideQuery<T extends keyof Tables = never> {
+  /**
+   * Creates a new GlideQuery instance
+   * 
+   * @param table - Table to query
+   * @param plan - Contains an array of Step objects describing the query (internal use)
+   * @param options - Additional options for the query
+   */
+  constructor(table: T, plan?: any[], options?: GlideQueryOptions);
+  
+  readonly table: T;
+  readonly plan: any[];
+  readonly type: 'GlideQuery';
+  
+  // WHERE CLAUSES
+  
+  /**
+   * Returns a new GlideQuery containing a where clause.
+   * 
+   * @example
+   * new GlideQuery('sys_user')
+   *     .where('active', true)
+   *     .where('last_login', '>', '2016-04-15')
+   * 
+   * @example
+   * // Nested query: active = true AND (priority = 1 OR severity = 1)
+   * new GlideQuery('incident')
+   *     .where('active', true)
+   *     .where(new GlideQuery()
+   *         .where('priority', 1)
+   *         .orWhere('severity', 1))
+   */
+  where(field: string, value: any): GlideQuery;
+  where(field: string, operator: WhereOperator, value: any): GlideQuery;
+  where(query: GlideQuery): GlideQuery;
+  
+  /**
+   * Returns a new GlideQuery containing an orWhere clause.
+   * Must be preceded by a single where, whereNull, or whereNotNull expression.
+   * 
+   * @example
+   * new GlideQuery('sys_user')
+   *     .where('failed_attempts', '>', 0)
+   *     .orWhere('last_login', '<', '2019-04-15')
+   *     .select()
+   */
+  orWhere(field: string, value: any): GlideQuery;
+  orWhere(field: string, operator: WhereOperator, value: any): GlideQuery;
+  orWhere(query: GlideQuery): GlideQuery;
+  
+  /**
+   * Returns a new GlideQuery containing NOT NULL clause.
+   * 
+   * @example
+   * new GlideQuery('sys_user')
+   *     .whereNotNull('first_name')
+   */
+  whereNotNull(field: string): GlideQuery;
+  
+  /**
+   * Returns a new GlideQuery containing NOT NULL clause (OR version).
+   * Must be preceded by a single where, whereNull, or whereNotNull expression.
+   * 
+   * @example
+   * new GlideQuery('sys_user')
+   *     .whereNotNull('first_name')
+   *     .orWhereNotNull('last_name')
+   */
+  orWhereNotNull(field: string): GlideQuery;
+  
+  /**
+   * Returns a new GlideQuery containing WHERE NULL clause.
+   * 
+   * @example
+   * new GlideQuery('sys_user')
+   *     .whereNull('last_name')
+   */
+  whereNull(field: string): GlideQuery;
+  
+  /**
+   * Returns a new GlideQuery containing WHERE NULL clause (OR version).
+   * Must be preceded by a single where, whereNull, or whereNotNull expression.
+   * 
+   * @example
+   * new GlideQuery('sys_user')
+   *     .whereNull('last_name')
+   *     .orWhereNull('first_name')
+   */
+  orWhereNull(field: string): GlideQuery;
+  
+  // RETRIEVE OPERATIONS
+  
+  /**
+   * Returns a single record using keyValues as a set of key-values to query by.
+   * Assumes the '=' operator for each key-value.
+   * 
+   * @example
+   * var user = new GlideQuery('sys_user')
+   *     .getBy({
+   *         first_name: 'Fred',
+   *         last_name: 'Luddy'
+   *     }, ['first_name', 'last_name', 'city', 'active'])
+   *     .orElse({
+   *         first_name: 'Nobody',
+   *         last_name: 'Found',
+   *         city: 'Nowhere',
+   *         active: false
+   *     });
+   */
+  getBy(keyValues: KeyValues, selectedFields?: string[]): Optional<GlideQueryRecord>;
+  
+  /**
+   * Returns a single record by querying primary key.
+   * 
+   * @example
+   * var user = new GlideQuery('sys_user')
+   *     .get('5137153cc611227c000bbd1bd8cd2005', ['first_name', 'last_name'])
+   *     .orElse({ first_name: 'Default', last_name: 'User' });
+   */
+  get(key: string, selectFields?: string[]): Optional<GlideQueryRecord>;
+  
+  /**
+   * Specifies which fields to return and returns a Stream containing the results.
+   * Records aren't actually read until a terminal Stream method is called.
+   * 
+   * @example
+   * var stream = new GlideQuery('sys_user')
+   *     .select('first_name', 'last_name', 'company$DISPLAY');
+   */
+  select(...fields: FieldWithFlag[]): Stream<GlideQueryRecord>;
+  
+  /**
+   * Similar to select(), but only returns an Optional with a single record.
+   * More efficient than select() if you only need one record.
+   * 
+   * @example
+   * var user = new GlideQuery('sys_user')
+   *     .where('zip', '12345')
+   *     .whereNotNull('last_name')
+   *     .selectOne('first_name', 'last_name', 'company$DISPLAY')
+   *     .get();
+   */
+  selectOne(...fields: FieldWithFlag[]): Optional<GlideQueryRecord>;
+  
+  // WRITE OPERATIONS
+  
+  /**
+   * Inserts a single record, returning an Optional of the newly-created record.
+   * 
+   * @example
+   * var fred = new GlideQuery('sys_user')
+   *     .insert({ first_name: 'Fred', last_name: 'Luddy' })
+   *     .get();
+   * 
+   * @throws {Error} When insert fails (e.g., when a business rule rejects the insert)
+   */
+  insert(keyValues: KeyValues, selectFields?: string[]): Optional<GlideQueryRecord>;
+  
+  /**
+   * Updates an existing record or inserts a new one if it doesn't exist.
+   * Uses the primary key(s) in the recordValues object.
+   * 
+   * @example
+   * // Insert a new record
+   * var user = new GlideQuery('sys_user')
+   *     .insertOrUpdate({
+   *         first_name: 'George',
+   *         last_name: 'Griffey'
+   *     })
+   *     .orElse(null);
+   * 
+   * @example
+   * // Update existing record
+   * var user = new GlideQuery('sys_user')
+   *     .insertOrUpdate({
+   *         sys_id: '2d0efd6c73662300bb513198caf6a72e',
+   *         first_name: 'George',
+   *         last_name: 'Griffey'
+   *     })
+   *     .orElse(null);
+   * 
+   * @throws {Error} When insert fails
+   */
+  insertOrUpdate(changes: KeyValues, selectFields?: string[], reason?: string): Optional<GlideQueryRecord>;
+  
+  /**
+   * Updates an existing record. Requires a where call specifying all existing primary keys.
+   * Returns an Optional of the newly-updated record.
+   * 
+   * @example
+   * new GlideQuery('sys_user')
+   *     .where('sys_id', userId)
+   *     .update({ city: 'Los Angeles' });
+   * 
+   * @throws {Error} When update fails
+   */
+  update(
+    changes: KeyValues, 
+    selectFields?: string[], 
+    reason?: string,
+    prefetchedSchema?: any,
+    planOverride?: any,
+    insertWhenNotFound?: boolean
+  ): Optional<GlideQueryRecord>;
+  
+  /**
+   * Updates all records matching the query with the values in the changes object.
+   * Returns the number of records updated.
+   * 
+   * @example
+   * new GlideQuery('sys_user')
+   *     .where('active', false)
+   *     .where('last_name', 'Griffey')
+   *     .updateMultiple({ active: true });
+   */
+  updateMultiple(changes: KeyValues): UpdateMultipleResult;
+  
+  /**
+   * Deletes all records matching the query.
+   * 
+   * @example
+   * new GlideQuery('sys_user')
+   *     .where('active', true)
+   *     .where('last_name', 'Jeter')
+   *     .deleteMultiple();
+   */
+  deleteMultiple(): void;
+  
+  /**
+   * Alias for deleteMultiple()
+   */
+  del(): void;
+  
+  // QUERY MODIFIERS
+  
+  /**
+   * Returns a GlideQuery which disables the running of business rules, script engines, and audit.
+   * 
+   * @example
+   * var query = new GlideQuery('task')
+   *     .disableWorkflow()
+   *     .where('active', true)
+   *     .updateMultiple({ priority: 1 });
+   */
+  disableWorkflow(): GlideQuery;
+  
+  /**
+   * Returns a GlideQuery which does not update sys fields such as sys_created_on, sys_updated_on, and sys_mod_count.
+   * Equivalent to using autoSysFields(false) with GlideRecord.
+   * 
+   * @example
+   * new GlideQuery('task')
+   *     .disableAutoSysFields()
+   *     .insert({ description: 'example', priority: 1 });
+   */
+  disableAutoSysFields(): GlideQuery;
+  
+  /**
+   * Returns a GlideQuery which forces an update even when no changes are made.
+   * Useful when you want to force a business rule to execute.
+   * Note: Cannot be called from a non-global scope.
+   * 
+   * @example
+   * new GlideQuery('task')
+   *     .forceUpdate()
+   *     .where('sys_id', taskId)
+   *     .update()
+   */
+  forceUpdate(): GlideQuery;
+  
+  /**
+   * Returns a GlideQuery which specifies that records should be returned in ascending order by a given field.
+   * 
+   * @example
+   * var query = new GlideQuery('incident')
+   *     .orderBy('number');
+   */
+  orderBy(field: string): GlideQuery;
+  
+  /**
+   * Returns a GlideQuery which specifies that records should be returned in descending order.
+   * Can be used with aggregate queries.
+   * 
+   * @example
+   * var query = new GlideQuery('incident')
+   *     .orderByDesc('number');
+   * 
+   * @example
+   * new GlideQuery('incident')
+   *     .aggregate('sum', 'child_incidents')
+   *     .groupBy('category')
+   *     .orderByDesc('sum', 'child_incidents')
+   */
+  orderByDesc(field: string): GlideQuery;
+  orderByDesc(aggregateType: AggregateType, field: string): GlideQuery;
+  
+  /**
+   * Returns a GlideQuery which limits the number of records returned.
+   * 
+   * @example
+   * var incidents = new GlideQuery('incident')
+   *     .limit(20)
+   *     .select('priority', 'description');
+   */
+  limit(limit: number): GlideQuery;
+  
+  /**
+   * By default GlideQuery uses GlideRecord. By calling withAcls(), GlideQuery will use GlideRecordSecure,
+   * which honors ACLs.
+   * 
+   * @example
+   * var users = new GlideQuery('sys_user')
+   *     .withAcls()
+   *     .limit(20)
+   *     .orderByDesc('first_name')
+   *     .select('first_name')
+   *     .toArray(100);
+   */
+  withAcls(): GlideQuery;
+  
+  /**
+   * By calling withSecurityDataFilters(), GlideQuery will apply Security Data Filters to the query.
+   * 
+   * @example
+   * var users = new GlideQuery('sys_user')
+   *     .withSecurityDataFilters()
+   *     .limit(20)
+   *     .orderByDesc('first_name')
+   *     .select('first_name')
+   *     .toArray(100);
+   */
+  withSecurityDataFilters(): GlideQuery;
+  
+  // AGGREGATE FUNCTIONS
+  
+  /**
+   * Returns the aggregate average of a given numeric field.
+   * Can be used on fields of type: integer, longint, float, double, currency.
+   * 
+   * @example
+   * var faults = new GlideQuery('cmdb_ci')
+   *     .avg('fault_count')
+   *     .orElse(0);
+   * 
+   * @throws {Error} When invalid field given
+   */
+  avg(field: string): Optional<number>;
+  
+  /**
+   * Returns the aggregate maximum of a given field.
+   * 
+   * @example
+   * var name = new GlideQuery('sys_user')
+   *     .max('first_name')
+   *     .orElse('');
+   * 
+   * @throws {Error} When invalid field given
+   */
+  max(field: string): Optional<any>;
+  
+  /**
+   * Returns the aggregate minimum of a given field.
+   * 
+   * @example
+   * var lowestModCount = new GlideQuery('sys_user')
+   *     .min('sys_mod_count')
+   *     .orElse(0);
+   * 
+   * @throws {Error} When invalid field given
+   */
+  min(field: string): Optional<any>;
+  
+  /**
+   * Returns the aggregate sum of a given numeric field.
+   * Can be used on fields of type: integer, longint, float, double, currency.
+   * 
+   * @example
+   * var totalFaults = new GlideQuery('cmdb_ci')
+   *     .sum('fault_count')
+   *     .orElse(0);
+   * 
+   * @throws {Error} When invalid field given
+   */
+  sum(field: string): Optional<number>;
+  
+  /**
+   * Returns the row count of records matching the query.
+   * 
+   * @example
+   * var userCount = new GlideQuery('sys_user')
+   *     .where('active', true)
+   *     .count();
+   */
+  count(): number;
+  
+  /**
+   * Groups query results. Used with aggregate().
+   * 
+   * @example
+   * new GlideQuery('task')
+   *     .aggregate('count')
+   *     .groupBy('contact_type')
+   *     .select()
+   */
+  groupBy(...fields: string[]): GlideQuery;
+  
+  /**
+   * Aggregates a field using an aggregate function.
+   * Used to build queries which aggregate against multiple fields and/or multiple aggregate functions.
+   * 
+   * @example
+   * new GlideQuery('task')
+   *     .aggregate('avg', 'reassignment_count')
+   *     .groupBy('contact_type')
+   *     .select()
+   */
+  aggregate(aggregateType: AggregateType, field: string): GlideQuery;
+  
+  /**
+   * Filters aggregate groups. Used with aggregate() and groupBy().
+   * 
+   * @example
+   * new GlideQuery('task')
+   *     .where('description', description)
+   *     .groupBy('priority')
+   *     .aggregate('sum', 'reassignment_count')
+   *     .having('sum', 'reassignment_count', '>', 4)
+   *     .select()
+   */
+  having(
+    aggregateType: AggregateType, 
+    field: string, 
+    operator: ComparisonOperator, 
+    value: number
+  ): GlideQuery;
+  
+  // UTILITY METHODS
+  
+  /**
+   * Returns a GlideRecord representing the current GlideQuery.
+   * The GlideRecord has not yet been queried, so query() may need to be called.
+   * May be a GlideAggregate in case aggregate queries are used.
+   * 
+   * @example
+   * var userGr = new GlideQuery('sys_user')
+   *     .where('active', true)
+   *     .whereNotNull('first_name')
+   *     .limit(10)
+   *     .toGlideRecord();
+   * userGr.query();
+   * while (userGr.next()) {
+   *     doSomething(userGr);
+   * }
+   */
+  toGlideRecord(): GlideRecord;
+  
+  /**
+   * Returns a string representation of the GlideQuery.
+   */
+  toString(): string;
+  
+  // STATIC METHODS
+  
+  /**
+   * Parses an encoded query string into a GlideQuery.
+   * 
+   * @example
+   * GlideQuery.parse('task', 'active=true^descriptionISNOTEMPTY')
+   *     .select('description')
+   *     .forEach(function (task) { gs.info(task.description); });
+   */
+  static parse(table: string, encodedQuery: string): GlideQuery;
+}

package/src/types/GlideQueryCondition.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The scoped QueryCondition API provides additional AND or OR conditions that can be added to the current condition,
+ * allowing you to build complex queries such as: category='hardware' OR category='software' AND priority='2' AND
+ * priority='1'
+ */
+export declare class GlideQueryCondition<T extends keyof Tables = never> {
+  constructor();
+
+  /**
+   * Adds an OR condition to the current condition.
+   */
+  addOrCondition(or: GlideQueryCondition<T>): void;
+
+  /**
+   * Adds an OR condition to the current condition.
+   */
+  addOrCondition<F extends keyof Tables[T], V extends Tables[T][F]>(
+    name: F,
+    value: V
+  ): GlideQueryCondition<T>;
+
+  /**
+   * Adds an OR condition to the current condition.
+   */
+  addOrCondition<F extends keyof Tables[T], V extends Tables[T][F]>(
+    name: F,
+    operator: any,
+    value: V
+  ): GlideQueryCondition<T>;
+  addSystemOrCondition<F extends keyof Tables[T], V extends Tables[T][F]>(
+    name: F,
+    operator: any,
+    value: V
+  ): GlideQueryCondition<T>;
+  addUserOrCondition<F extends keyof Tables[T], V extends Tables[T][F]>(
+    name: F,
+    operator: any,
+    value: V
+  ): GlideQueryCondition<T>;
+
+  /**
+   * Adds an AND condition to the current condition.
+   */
+  addCondition(and: GlideQueryCondition<T>): void;
+
+  /**
+   * Adds an AND condition to the current condition.
+   */
+  addCondition<F extends keyof Tables[T], V extends Tables[T][F]>(
+    name: F,
+    value: V
+  ): GlideQueryCondition<T>;
+
+  /**
+   * Adds an AND condition to the current condition.
+   */
+  addCondition<F extends keyof Tables[T], V extends Tables[T][F]>(
+    name: F,
+    oper: string,
+    value: V
+  ): GlideQueryCondition<T>;
+
+  addCondition<F extends keyof Tables[T], V extends Tables[T][F]>(
+    name: F,
+    operator: any,
+    value: V
+  ): GlideQueryCondition<T>;
+  addSystemCondition<F extends keyof Tables[T], V extends Tables[T][F]>(
+    name: F,
+    operator: any,
+    value: V
+  ): GlideQueryCondition<T>;
+
+  addUserCondition<F extends keyof Tables[T], V extends Tables[T][F]>(
+    name: F,
+    operator: any,
+    value: V
+  ): GlideQueryCondition<T>;
+
+  addQueryHint(name: string): void;
+  addQueryHint(name: string, value: any): void;
+}