ember-source 4.8.0-alpha.5 → 4.8.0-beta.2

package/types/preview/@ember/runloop/index.d.ts

@@ -0,0 +1,175 @@
+declare module '@ember/runloop' {
+  import {
+    EmberMethod,
+    EmberMethodParams,
+    AnyFn,
+    EmberMethodReturn,
+  } from 'ember/-private/type-utils';
+  import { EmberRunQueues } from '@ember/runloop/-private/types';
+  import { EmberRunTimer } from '@ember/runloop/types';
+  import '@ember/runloop/-private/backburner';
+
+  /**
+   * Runs the passed target and method inside of a RunLoop, ensuring any
+   * deferred actions including bindings and views updates are flushed at the
+   * end.
+   */
+  export function run<M extends AnyFn>(method: M): ReturnType<M>;
+  export function run<T, M extends EmberMethod<T>>(
+    target: T,
+    method: M,
+    ...args: EmberMethodParams<T, M>
+  ): EmberMethodReturn<T, M>;
+
+  /**
+   * If no run-loop is present, it creates a new one. If a run loop is
+   * present it will queue itself to run on the existing run-loops action
+   * queue.
+   */
+  export function join<M extends AnyFn>(
+    method: M,
+    ...args: Parameters<M>
+  ): ReturnType<M> | undefined;
+  export function join<T, M extends EmberMethod<T>>(
+    target: T,
+    method: M,
+    ...args: EmberMethodParams<T, M>
+  ): EmberMethodReturn<T, M> | undefined;
+
+  /**
+   * Allows you to specify which context to call the specified function in while
+   * adding the execution of that function to the Ember run loop. This ability
+   * makes this method a great way to asynchronously integrate third-party libraries
+   * into your Ember application.
+   */
+  // NOTE: it would be nice to make this curry arguments, which is how it actually
+  // works, but that is a *lot* of type shenanigans, and also diverges from the
+  // `Function.prototype.bind` implementation. We should track the latter, despite
+  // the loss of safety, because it makes interop cleaner.
+  export function bind<T, M extends EmberMethod<T>>(
+    target: T,
+    method: M,
+    ...args: any[]
+  ): (...args: any[]) => EmberMethodReturn<T, M>;
+
+  /**
+   * Begins a new RunLoop. Any deferred actions invoked after the begin will
+   * be buffered until you invoke a matching call to `run.end()`. This is
+   * a lower-level way to use a RunLoop instead of using `run()`.
+   */
+  export function begin(): void;
+
+  /**
+   * Ends a RunLoop. This must be called sometime after you call
+   * `run.begin()` to flush any deferred actions. This is a lower-level way
+   * to use a RunLoop instead of using `run()`.
+   */
+  export function end(): void;
+
+  /**
+   * Adds the passed target/method and any optional arguments to the named
+   * queue to be executed at the end of the RunLoop. If you have not already
+   * started a RunLoop when calling this method one will be started for you
+   * automatically.
+   */
+  export function schedule<T, M extends EmberMethod<T>>(
+    queue: EmberRunQueues,
+    target: T,
+    method: M,
+    ...args: EmberMethodParams<T, M>
+  ): EmberRunTimer;
+  export function schedule<M extends AnyFn>(
+    queue: EmberRunQueues,
+    method: M,
+    ...args: Parameters<M>
+  ): EmberRunTimer;
+
+  /**
+   * Invokes the passed target/method and optional arguments after a specified
+   * period of time. The last parameter of this method must always be a number
+   * of milliseconds.
+   */
+  export function later(method: AnyFn, wait: number): EmberRunTimer;
+  export function later<T, M extends EmberMethod<T>>(
+    ...args: [target: T, method: M, ...args: EmberMethodParams<T, M>, wait: number]
+  ): EmberRunTimer;
+
+  /**
+   * Schedule a function to run one time during the current RunLoop. This is equivalent
+   * to calling `scheduleOnce` with the "actions" queue.
+   */
+  export function once<T, M extends EmberMethod<T>>(
+    target: T,
+    method: M,
+    ...args: EmberMethodParams<T, M>
+  ): EmberRunTimer;
+
+  export function once<T, M extends keyof T>(
+    target: T,
+    method: M,
+    ...args: EmberMethodParams<T, M>
+  ): EmberRunTimer;
+
+  /**
+   * Schedules a function to run one time in a given queue of the current RunLoop.
+   * Calling this method with the same queue/target/method combination will have
+   * no effect (past the initial call).
+   */
+  export function scheduleOnce<T, M extends EmberMethod<T>>(
+    queue: EmberRunQueues,
+    target: T,
+    method: M,
+    ...args: EmberMethodParams<T, M>
+  ): EmberRunTimer;
+
+  /**
+   * Schedules an item to run from within a separate run loop, after
+   * control has been returned to the system. This is equivalent to calling
+   * `run.later` with a wait time of 1ms.
+   */
+  export function next<T, M extends EmberMethod<T>>(
+    target: T,
+    method: M,
+    ...args: EmberMethodParams<T, M>
+  ): EmberRunTimer;
+  export function next<M extends AnyFn>(method: M, ...args: Parameters<M>): EmberRunTimer;
+
+  /**
+   * Cancels a scheduled item. Must be a value returned by `run.later()`,
+   * `run.once()`, `run.scheduleOnce()`, `run.next()`, `run.debounce()`, or
+   * `run.throttle()`.
+   */
+  export function cancel(timer?: EmberRunTimer): boolean;
+
+  /**
+   * Delay calling the target method until the debounce period has elapsed
+   * with no additional debounce calls. If `debounce` is called again before
+   * the specified time has elapsed, the timer is reset and the entire period
+   * must pass again before the target method is called.
+   */
+  export function debounce(method: AnyFn, wait: number, immediate?: boolean): EmberRunTimer;
+  export function debounce<Target, M extends EmberMethod<Target>>(
+    ...args: [
+      target: Target,
+      method: M,
+      ...args: EmberMethodParams<Target, M>,
+      wait: number,
+      immediate?: boolean
+    ]
+  ): EmberRunTimer;
+
+  /**
+   * Ensure that the target method is never called more frequently than
+   * the specified spacing period. The target method is called immediately.
+   */
+  export function throttle(method: AnyFn, spacing: number, immediate?: boolean): EmberRunTimer;
+  export function throttle<T, M extends EmberMethod<T>>(
+    ...args: [
+      target: T,
+      method: M,
+      ...methodArgs: EmberMethodParams<T, M>,
+      spacing: number,
+      immediate?: boolean
+    ]
+  ): EmberRunTimer;
+}

package/types/preview/@ember/runloop/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json"
+}

package/types/preview/@ember/runloop/types.d.ts

@@ -0,0 +1,5 @@
+declare module '@ember/runloop/types' {
+  export interface EmberRunTimer {
+    __ember_run_timer_brand__: boolean;
+  }
+}

package/types/preview/@ember/service/index.d.ts

@@ -0,0 +1,25 @@
+declare module '@ember/service' {
+  import EmberObject from '@ember/object';
+  import type { BasicComputedProperty } from '@ember/object/computed';
+
+  export default class Service extends EmberObject {}
+  /**
+   * Creates a property that lazily looks up a service in the container. There
+   * are no restrictions as to what objects a service can be injected into.
+   */
+  export function inject(): Service; // @inject() foo, foo: inject()
+  export function inject(target: object, propertyKey: string | symbol): void; // @inject foo
+  export function inject<K extends keyof Registry>(name: K): Registry[K] & BasicComputedProperty; // @inject('store') foo      @inject() foo
+
+  /**
+   * Creates a property that lazily looks up a service in the container. There
+   * are no restrictions as to what objects a service can be injected into.
+   */
+  export function service(): Service; // @service() foo, foo: service()
+  export function service(target: object, propertyKey: string | symbol): void; // @service foo
+  export function service<K extends keyof Registry>(name: K): Registry[K] & BasicComputedProperty; // @service('store') foo      @service() foo
+
+  // A type registry for Ember `Service`s. Meant to be declaration-merged so
+  // string lookups resolve to the correct type.
+  interface Registry {}
+}

package/types/preview/@ember/service/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json"
+}

package/types/preview/@ember/string/index.d.ts

@@ -0,0 +1,9 @@
+declare module '@ember/string' {
+  export function camelize(str: string): string;
+  export function capitalize(str: string): string;
+  export function classify(str: string): string;
+  export function dasherize(str: string): string;
+  export function decamelize(str: string): string;
+  export function underscore(str: string): string;
+  export function w(str: string): string[];
+}

package/types/preview/@ember/string/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json"
+}

package/types/preview/@ember/template/-private/handlebars.d.ts

@@ -0,0 +1,7 @@
+declare module '@ember/template/-private/handlebars' {
+  export class SafeString {
+    constructor(str: string);
+    toString(): string;
+    toHTML(): string;
+  }
+}

package/types/preview/@ember/template/index.d.ts

@@ -0,0 +1,5 @@
+declare module '@ember/template' {
+  import { SafeString } from '@ember/template/-private/handlebars';
+  export function htmlSafe(str: string): SafeString;
+  export function isHTMLSafe(str: unknown): str is SafeString;
+}

package/types/preview/@ember/template/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json"
+}

package/types/preview/@ember/test/adapter.d.ts

@@ -0,0 +1,22 @@
+declare module '@ember/test/adapter' {
+  /**
+   * The primary purpose of this class is to create hooks that can be implemented
+   * by an adapter for various test frameworks.
+   */
+  export default class Adapter {
+    /**
+     * This callback will be called whenever an async operation is about to start.
+     */
+    asyncStart(): unknown;
+    /**
+     * This callback will be called whenever an async operation has completed.
+     */
+    asyncEnd(): unknown;
+    /**
+     * Override this method with your testing framework's false assertion.
+     * This function is called whenever an exception occurs causing the testing
+     * promise to fail.
+     */
+    exception(error: string): unknown;
+  }
+}

package/types/preview/@ember/test/index.d.ts

@@ -0,0 +1,49 @@
+declare module '@ember/test' {
+  import Application from '@ember/application';
+
+  /**
+   * `registerHelper` is used to register a test helper that will be injected
+   * when `App.injectTestHelpers` is called.
+   */
+  export function registerHelper(
+    name: string,
+    helperMethod: (app: Application, ...args: any[]) => unknown,
+    options?: object
+  ): unknown;
+  /**
+   * `registerAsyncHelper` is used to register an async test helper that will be injected
+   * when `App.injectTestHelpers` is called.
+   */
+  export function registerAsyncHelper(
+    name: string,
+    helperMethod: (app: Application, ...args: any[]) => unknown
+  ): void;
+
+  /**
+   * Remove a previously added helper method.
+   */
+  export function unregisterHelper(name: string): void;
+
+  /**
+   * This allows ember-testing to play nicely with other asynchronous
+   * events, such as an application that is waiting for a CSS3
+   * transition or an IndexDB transaction. The waiter runs periodically
+   * after each async helper (i.e. `click`, `andThen`, `visit`, etc) has executed,
+   * until the returning result is truthy. After the waiters finish, the next async helper
+   * is executed and the process repeats.
+   */
+  export function registerWaiter(callback: () => boolean): unknown;
+  export function registerWaiter<Context>(
+    context: Context,
+    callback: (this: Context) => boolean
+  ): unknown;
+  /**
+   * `unregisterWaiter` is used to unregister a callback that was
+   * registered with `registerWaiter`.
+   */
+  export function unregisterWaiter(callback: () => boolean): unknown;
+  export function unregisterWaiter<Context>(
+    context: Context,
+    callback: (this: Context) => boolean
+  ): unknown;
+}

package/types/preview/@ember/test/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json"
+}

package/types/preview/@ember/utils/-private/types.d.ts

@@ -0,0 +1,39 @@
+declare module '@ember/utils/-private/types' {
+  import type { AnyFn } from 'ember/-private/type-utils';
+  import NativeArray from '@ember/array/-private/native-array';
+
+  // prettier-ignore
+  type _KeysOfType<Key extends keyof TypeLookup, Type> =
+    // Checks non-`const` versions, and correctly resolves those types
+    // constructed via e.g. the `Number` constructor.
+    TypeLookup[Key] extends Type ? Key :
+    // Checks `const` versions, e.g. handling strict function types when also
+    // using a const-valued function like `const x = () => 4 as const`.
+    Type extends TypeLookup[Key] ? Key : never;
+
+  // prettier-ignore
+  type KeysOfType<Type> =
+    { [Key in keyof TypeLookup]: _KeysOfType<Key, Type> }[keyof TypeLookup];
+
+  // Since `TypeLookup` resolves all *other* types, including `null` and
+  // `undefined`, we can assume that if the type does *not* resolve from
+  // `KeysOfType`, it is safe to treat it as 'object'.
+  export type TypeOf<T> = KeysOfType<T> extends never ? 'object' : KeysOfType<T>;
+
+  export interface TypeLookup {
+    string: string;
+    number: number;
+    boolean: boolean;
+    regexp: RegExp;
+    function: AnyFn;
+    array: Array<unknown> | NativeArray<unknown>;
+    error: Error;
+    filelist: FileList;
+    date: Date;
+    null: null;
+    undefined: undefined;
+  }
+
+  // Don't export anything but the required type util
+  export {};
+}

package/types/preview/@ember/utils/index.d.ts

@@ -0,0 +1,42 @@
+declare module '@ember/utils' {
+  import { TypeOf } from '@ember/utils/-private/types';
+
+  /**
+   * Compares two javascript values and returns:
+   */
+  export function compare(v: unknown, w: unknown): number;
+
+  /**
+   * A value is blank if it is empty or a whitespace string.
+   */
+  export function isBlank(obj?: unknown): boolean;
+
+  /**
+   * Verifies that a value is `null` or an empty string, empty array,
+   * or empty function.
+   */
+  export function isEmpty(obj?: unknown): boolean;
+
+  /**
+   * Compares two objects, returning true if they are equal.
+   */
+  export function isEqual(a: unknown, b: unknown): boolean;
+
+  /**
+   * Returns true if the passed value is null or undefined. This avoids errors
+   * from JSLint complaining about use of ==, which can be technically
+   * confusing.
+   */
+  export function isNone(obj?: unknown): obj is null | undefined;
+
+  /**
+   * A value is present if it not `isBlank`.
+   */
+  export function isPresent(obj?: unknown): boolean;
+
+  /**
+   * Returns a consistent type for the passed object.
+   */
+  export function typeOf<T>(value: T): TypeOf<T>;
+  export function typeOf(): 'undefined';
+}

package/types/preview/@ember/utils/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json"
+}

package/types/preview/ember/-private/type-utils.d.ts

@@ -0,0 +1,54 @@
+declare module 'ember/-private/type-utils' {
+  // These are utility types used throughout the Ember type definitions. They
+  // should *never* be used in end user code.
+
+  /** A safe-ish type representing any function. */
+  export type AnyFn = (...args: any[]) => unknown;
+
+  export type AnyMethod<Target> = (this: Target, ...args: any[]) => unknown;
+
+  export type MethodsOf<O> = {
+    [K in keyof O]: O[K] extends AnyFn ? O[K] : never;
+  };
+
+  // Not just `keyof MethodsOf<O>` because that doesn't correctly exclude all the
+  // `never` fields.
+  export type MethodNamesOf<O> = {
+    [K in keyof O]: O[K] extends AnyFn ? K : never;
+  }[keyof O];
+
+  export type MethodParams<T, M extends MethodNamesOf<T>> = Parameters<MethodsOf<T>[M]>;
+
+  export type MethodReturns<T, M extends MethodNamesOf<T>> = ReturnType<MethodsOf<T>[M]>;
+
+  // prettier-ignore
+  /** Get the return value of a method string name or a function. */
+  export type EmberMethodParams<T, M extends EmberMethod<T>> =
+  M extends AnyMethod<T> ? Parameters<M> :
+  M extends keyof T ? T[M] extends AnyMethod<T> ? Parameters<MethodsOf<T>[M]> : never :
+  never;
+
+  // prettier-ignore
+  /** Get the return value of a method string name or a function. */
+  export type EmberMethodReturn<T, M extends EmberMethod<T>> =
+  M extends AnyMethod<T> ? ReturnType<M> :
+  M extends keyof T ? T[M] extends AnyMethod<T> ? ReturnType<MethodsOf<T>[M]> : never :
+  never;
+
+  /**
+   * A type utility for Ember's common name-of-object-on-target-or-function
+   * pattern for e.g. event handlers.
+   */
+  export type EmberMethod<Target> = AnyMethod<Target> | keyof Target;
+
+  // A way of representing non-user-constructible types. You can conveniently use
+  // this by doing `interface Type extends Data<'some-type-name'> { ... }` for
+  // simple types, and/or you can type-parameterize it as makes sense for your use
+  // case (see e.g. `@ember/component/helper`'s use with functional helpers).
+  const Data: unique symbol;
+  export class Opaque<Data> {
+    private declare [Data]: Data;
+  }
+
+  export {};
+}