@strapi/strapi 4.2.3 → 4.3.0

package/lib/types/core/strapi/index.d.ts

@@ -0,0 +1,391 @@
+import type Koa from 'koa';
+import { Database } from '@strapi/database';
+
+import type { StringMap } from './utils';
+import type { GenericController } from '../core-api/controller'
+
+/**
+ * The Strapi interface implemented by the main Strapi class.
+ */
+export interface Strapi {
+  /**
+   * Getter for the Strapi enterprise edition configuration
+   */
+  readonly EE: any;
+
+  /**
+   * Getter for the Strapi configuration container
+   */
+  readonly config: any;
+
+  /**
+   * Getter for the Strapi auth container
+   */
+  readonly auth: any;
+
+  /**
+   * Getter for the Strapi sanitizers container
+   */
+  readonly sanitizers: any;
+
+  /**
+   * Getter for the Strapi services container
+   *
+   * It returns all the registered services
+   */
+  readonly services: StringMap<Service>;
+
+  /**
+   * Find a service using its unique identifier
+   */
+  service<T extends Service = unknown>(uid: string): T | undefined;
+
+  /**
+   * Getter for the Strapi controllers container
+   *
+   * It returns all the registered controllers
+   */
+  readonly controllers: StringMap<GenericController>;
+
+  /**
+   * Find a controller using its unique identifier
+   */
+  controller(uid: string): GenericController | undefined;
+
+  /**
+   * Getter for the Strapi content types container
+   *
+   * It returns all the registered content types
+   */
+  readonly contentTypes: any;
+
+  /**
+   * Find a content type using its unique identifier
+   */
+  contentType(uid: string): any;
+
+  /**
+   * Getter for the Strapi policies container
+   *
+   * It returns all the registered policies
+   */
+  readonly policies: any;
+
+  /**
+   * Find a policy using its name
+   */
+  policy(name: string): any;
+
+  /**
+   * Getter for the Strapi middlewares container
+   *
+   * It returns all the registered middlewares
+   */
+  readonly middlewares: any;
+
+  /**
+   * Find a middleware using its name
+   */
+  middleware(): any;
+
+  /**
+   * Getter for the Strapi plugins container
+   *
+   * It returns all the registered plugins
+   */
+  readonly plugins: any;
+
+  /**
+   * Find a plugin using its name
+   */
+  plugin(name: string): any;
+
+  /**
+   * Getter for the Strapi hooks container
+   *
+   * It returns all the registered hooks
+   */
+  readonly hooks: any;
+
+  /**
+   * Find a hook using its name
+   */
+  hook(): any;
+
+  /**
+   * Getter for the Strapi APIs container
+   *
+   * It returns all the registered APIs
+   */
+  readonly api: any;
+
+  /**
+   * Strapi Register Lifecycle.
+   *
+   * - Load
+   *   - The user application
+   *   - The plugins
+   *   - The admin
+   *   - The APIs
+   *   - The components
+   *   - The middlewares
+   *   - The policies
+   * - Trigger Strapi internal bootstrap
+   * - Create the webhooks runner
+   * - Create the internal hooks registry.
+   * - Init the telemetry cron job and middleware
+   * - Run all the `register` lifecycle methods loaded by the user application or the enabled plugins
+   */
+  register(): Promise<Strapi>;
+
+  /**
+   * Bootstraping phase.
+   *
+   * - Load all the content types
+   * - Initialize the database layer
+   * - Initialize the entity service
+   * - Run the schemas/database synchronization
+   * - Start the webhooks and initializing middlewares and routes
+   * - Run all the `bootstrap` lifecycle methods loaded by the
+   * user application or the enabled plugins
+   */
+  bootstrap(): Promise<Strapi>;
+
+  /**
+   * Destroy phase
+   *
+   * - Destroy Strapi server
+   * - Run all the `destroy` lifecycle methods loaded by the
+   * user application or the enabled plugins
+   * - Cleanup the event hub
+   * - Gracefully stop the database
+   * - Stop the telemetry and cron instance
+   * - Cleanup the global scope by removing global.strapi
+   */
+  destroy(): Promise<void>;
+
+  /**
+   * Run all functions registered for a given lifecycle. (Strapi core, user app, plugins)
+   */
+  runLifecyclesFunctions<T extends Lifecycles[keyof Lifecycles]>(lifecycleName: T): Promise<void>;
+
+  /**
+   * Load the application if needed and start the server
+   */
+  start(): Promise<void>;
+
+  /**
+   * Stop the server and provide a custom error and message
+   */
+  stopWithError<TError = unknown>(error: TError, customMessage?: string): void;
+
+  /**
+   * Gracefully stop the server
+   * Call the destroy method.
+   */
+  stop(code?: number): void;
+
+  /**
+   * Load the server and the user application.
+   * It basically triggers the register and bootstrap phases
+   */
+  load(): Promise<Strapi>;
+
+  /**
+   * Restart the server and reload all the configuration.
+   * It re-runs all the lifecycles phases.
+   * 
+   * @example
+   * ``` ts
+   * setImmediate(() => strapi.reload());
+   * ```
+   */
+  reload(): () => void;
+
+  /**
+   * Initialize and start all the webhooks registered in the webhook store
+   */
+  startWebhooks(): Promise<void>;
+
+  /**
+   * Method called when the server is fully initialized and listen to incomming requests.
+   * It handles tasks such as logging the startup message
+   * or automatically opening the administration panel.
+   */
+  postListen(): Promise<void>;
+
+  /**
+   * Start listening for incomming requests
+   */
+  listen(): Promise<void | Error>;
+
+  /**
+   * Opent he administration panel in a browser if the option is enabled.
+   * You can disable it using the admin.autoOpen configuration variable.
+   * 
+   * Note: It only works in development envs.
+   */
+  openAdmin(options: { isInitialized: boolean }): Promise<void>;
+
+  /**
+   * Load the admin panel server logic into the server code and initialize its configuration. 
+   */
+  loadAdmin(): Promise<void>;
+
+  /**
+   * Resolve every enabled plugin and load them into the application.
+   */
+  loadPlugins(): Promise<void>;
+
+  /**
+   * Load every global policies in the policies container by
+   * reading from the `strapi.dirs.dist.policies` directory.
+   */
+  loadPolicies(): Promise<void>;
+
+  /**
+   * Load every APIs and their components (config, routes, controllers, services,
+   * policies, middlewares, content-types) in the API container.
+   */
+  loadAPIs(): Promise<void>;
+
+  /**
+   * Resolve every components in the user application and store them in `strapi.components`
+   */
+  loadComponents(): Promise<void>;
+
+  /**
+   * Load every global and core middlewares in the middlewares container by
+   * reading from the `strapi.dirs.dist.middlewares` and internal middlewares directory.
+   */
+  loadMiddlewares(): Promise<void>;
+
+  /**
+   * Load the user application in the server by reading the `src/index.js` file.
+   */
+  loadApp(): Promise<void>;
+
+  /**
+   * Add internal hooks to the hooks container.
+   * Those hooks are meant for internal usage and might break in future releases.
+   */
+  registerInternalHooks(): void;
+
+  /**
+   * Find a model (content-type, component) based on its unique identifier.
+   */
+  getModel(uid: string): any;
+
+  /**
+   * Binds database queries for a specific model based on its unique identifier.
+   */
+  query(uid: string): any;
+
+  /**
+   * Main Strapi container holding all the registries and providers (config, content-types, services, policies, etc...)
+   */
+  container: any;
+
+  /**
+   * References to all the directories handled by Strapi 
+   */
+  dirs: StrapiDirectories;
+
+  /**
+   * Internal flag used to check if the application has been loaded
+   */
+  isLoaded: boolean;
+
+  /**
+   * Fully reload the application
+   */
+  reload(): void;
+
+  /**
+   * Holds a reference to the Koa application and the http server used by Strapi
+   */
+  server: any;
+
+  /**
+   * Strapi util used to manage application files
+   */
+  fs: any;
+
+  /**
+   * Event hub used to send and receive events from anywhere in the application
+   */
+  eventHub: any;
+
+  /**
+   * Internal util used to log stats and messages on application Startup
+   */
+  startupLogger: any;
+
+  /**
+   * Strapi logger used to send errors, warning or information messages 
+   */
+  log: any;
+
+
+  /**
+   * Used to manage cron within Strapi
+   */
+  cron: any;
+
+  /**
+   * Telemetry util used to collect anonymous data on the application usage
+   */
+  telemetry: any;
+
+  /**
+   * Strapi DB layer instance
+   */
+  db: Database;
+
+  /**
+   * Core Store accessor
+   */
+  store: any;
+
+  /**
+   * Entity Validator instance
+   */
+  entityValidator: any;
+
+  /**
+   * Entity Service instance
+   */
+  entityService: any;  
+}
+
+export interface Lifecycles {
+  REGISTER: 'register';
+  BOOTSTRAP: 'bootstrap';
+  DESTROY: 'destroy';
+}
+
+export interface StrapiDirectories {
+  static: {
+    public: string;
+  };
+  app: {
+    root: string;
+    src: string;
+    api: string;
+    components: string;
+    extensions: string;
+    policies: string;
+    middlewares: string;
+    config: string;
+  };
+  dist: {
+    root: string;
+    src: string;
+    api: string;
+    components: string;
+    extensions: string;
+    policies: string;
+    middlewares: string;
+    config: string;
+  };
+}

package/lib/types/factories.d.ts

@@ -0,0 +1,60 @@
+import { Service } from '../core-api/service';
+import { Controller, GenericController } from '../core-api/controller';
+import { Middleware } from '../middlewares';
+import { Policy } from '../core/registries/policies';
+import { Strapi } from '@strapi/strapi';
+
+type ControllerConfig<T extends Controller = Controller> = T;
+
+type ServiceConfig = Service;
+
+type HandlerConfig = {
+  auth?: false | { scope: string[] };
+  policies?: Array<string | Policy | { name: string; config: object }>;
+  middlewares?: Array<string | Middleware | { name: string; config: object }>;
+};
+
+type SingleTypeRouterConfig = {
+  find?: HandlerConfig;
+  update?: HandlerConfig;
+  delete?: HandlerConfig;
+};
+
+type CollectionTypeRouterConfig = {
+  find?: HandlerConfig;
+  findOne?: HandlerConfig;
+  create?: HandlerConfig;
+  update?: HandlerConfig;
+  delete?: HandlerConfig;
+};
+
+type RouterConfig = {
+  prefix?: string;
+  only: string[];
+  except?: string[];
+  config: SingleTypeRouterConfig | CollectionTypeRouterConfig;
+};
+
+interface Route {
+  method: string;
+  path: string;
+}
+interface Router {
+  prefix: string;
+  routes: Route[];
+}
+
+type ControllerCallback<T extends GenericController = GenericController> = (params: {
+  strapi: Strapi;
+}) => T;
+type ServiceCallback<T extends Service = Service> = (params: { strapi: Strapi }) => T;
+
+export function createCoreRouter(uid: string, cfg?: RouterConfig = {}): () => Router;
+export function createCoreController<T extends GenericController = GenericController>(
+  uid: string,
+  cfg?: ControllerCallback<T> | T = {}
+): () => T & Controller;
+export function createCoreService<T extends Service = Service>(
+  uid: string,
+  cfg?: ServiceCallback<T> | T = {}
+): () => T;

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './core';
+
+export * as utils from './utils'
+export * as factories from './factories';

package/lib/types/utils.d.ts

@@ -0,0 +1,95 @@
+/**
+ *
+ * Common utilities used across Strapi typings
+ *
+ * */
+
+/**
+ *
+ * Extract the array values into an union type
+ *
+ **/
+export type GetArrayValues<T extends Array<unknown>> = T extends Array<infer U> ? U : never;
+
+/**
+ * Creates a record where every key is a string and every value is `T`
+ */
+export type StringRecord<T> = Record<string, T>;
+
+/**
+ * Retrieve object's (`T`) keys if they extends the given `U` type.
+ *
+ * @example
+ * type X = KeysBy<{ foo: 'bar', bar: 'foo', foobar: 2 }, string>
+ * // 'foo' | 'bar'
+ *
+ * type Base = { x: 'foo' | 'bar' };
+ * type Obj = { foo: { x: 'foo' }, bar: { x: 'bar' }, other: { x: '42' } };
+ * type X = KeysBy<Obj, Base>
+ * // 'foo' | 'bar'
+ */
+export type KeysBy<T, U> = {
+  [key in keyof T]: T[key] extends U ? key : never;
+}[keyof T];
+
+/**
+ * Retrieve object's (`T`) properties if their value extends the given `U` type.
+ *
+ * @example
+ * type X = KeysBy<{ foo: 'bar', bar: 'foo', foobar: 2 }, string>
+ * // { foo: 'bar', bar: 'foo' }
+ *
+ * type Base = { x: 'foo' | 'bar' };
+ * type Obj = { foo: { x: 'foo' }, bar: { x: 'bar' }, other: { x: '42' } };
+ * type X = KeysBy<Obj, Base>
+ * // { foo: { x: 'foo' }, bar: { x: 'bar' } }
+ */
+export type PickBy<T, U> = Pick<T, KeysBy<T, U>>;
+
+/**
+ * Assign a default value `U` to `T` if `T` is of type `never`
+ *
+ * @example
+ * type X = NeverGuard<{ foo: 'bar' }, string>
+ * // { foo: 'bar' }
+ *
+ * type X = NeverGuard<never>
+ * // unknown
+ *
+ * type X = NeverGuard<never, string>
+ * // string
+ */
+export type NeverGuard<T, U = unknown> = [T] extends [never] ? U : T;
+
+/**
+ * Dynamic type based on the keys of `Strapi.Schemas`.
+ * It represents all the registered schemas' UID as a union type.
+ *
+ * @example
+ *
+ * declare global {
+ *   namespace Strapi {
+ *     interface Schemas {
+ *       'api::foo.foo': CollectionTypeSchema;
+ *       'api::bar.bar': ComponentSchema;
+ *     }
+ *   }
+ * }
+ *
+ * type X = SchemaUID;
+ * // 'api::foo.foo' | 'api::bar.bar'
+ */
+export type SchemaUID = keyof Strapi.Schemas;
+
+/**
+ * Get the type of a specific key `U` in `T`
+ *
+ * @example
+ *
+ * type X = Get<{ foo: 'bar', 'bar': 'foo' }, 'foo'>
+ * // 'bar'
+ *
+ * type X = Get<{ foo: 'bar', 'bar': 'foo' }, 'bar'>
+ * // 'foo'
+ */
+export type Get<T, U extends keyof T> = T[U];

package/lib/utils/get-dirs.js

@@ -2,16 +2,30 @@
 
 const { join, resolve } = require('path');
 
-const getDirs = (root, { strapi }) => ({
-  root,
-  src: join(root, 'src'),
-  api: join(root, 'src', 'api'),
-  components: join(root, 'src', 'components'),
-  extensions: join(root, 'src', 'extensions'),
-  policies: join(root, 'src', 'policies'),
-  middlewares: join(root, 'src', 'middlewares'),
-  config: join(root, 'config'),
-  public: resolve(root, strapi.config.get('server.dirs.public')),
+const getDirs = ({ app: appDir, dist: distDir }, { strapi }) => ({
+  dist: {
+    root: distDir,
+    src: join(distDir, 'src'),
+    api: join(distDir, 'src', 'api'),
+    components: join(distDir, 'src', 'components'),
+    extensions: join(distDir, 'src', 'extensions'),
+    policies: join(distDir, 'src', 'policies'),
+    middlewares: join(distDir, 'src', 'middlewares'),
+    config: join(distDir, 'config'),
+  },
+  app: {
+    root: appDir,
+    src: join(appDir, 'src'),
+    api: join(appDir, 'src', 'api'),
+    components: join(appDir, 'src', 'components'),
+    extensions: join(appDir, 'src', 'extensions'),
+    policies: join(appDir, 'src', 'policies'),
+    middlewares: join(appDir, 'src', 'middlewares'),
+    config: join(appDir, 'config'),
+  },
+  static: {
+    public: resolve(appDir, strapi.config.get('server.dirs.public')),
+  },
 });
 
 module.exports = getDirs;

package/lib/utils/import-default.js

@@ -0,0 +1,10 @@
+'use strict';
+
+const importDefault =
+  (this && this.importDefault) ||
+  function(modName) {
+    const mod = require(modName);
+    return mod && mod.__esModule ? mod.default : mod;
+  };
+
+module.exports = importDefault;

package/lib/utils/index.js

@@ -3,9 +3,11 @@
 const openBrowser = require('./open-browser');
 const isInitialized = require('./is-initialized');
 const getDirs = require('./get-dirs');
+const importDefault = require('./import-default');
 
 module.exports = {
   isInitialized,
   openBrowser,
   getDirs,
+  importDefault,
 };

package/lib/utils/lifecycles.js

@@ -0,0 +1,15 @@
+'use strict';
+
+/**
+ * A map of all the available Strapi lifecycles
+ * @type {import('@strapi/strapi').Core.Lifecycles}
+ */
+const LIFECYCLES = {
+  REGISTER: 'register',
+  BOOTSTRAP: 'bootstrap',
+  DESTROY: 'destroy',
+};
+
+module.exports = {
+  LIFECYCLES,
+};

package/lib/utils/machine-id.js

@@ -1,14 +1,14 @@
 'use strict';
 
 const { machineIdSync } = require('node-machine-id');
-const uuid = require('uuid');
+const { v4: uuidv4 } = require('uuid');
 
 module.exports = () => {
   try {
     const deviceId = machineIdSync();
     return deviceId;
   } catch (error) {
-    const deviceId = uuid();
+    const deviceId = uuidv4();
     return deviceId;
   }
 };

package/lib/utils/update-notifier/index.js

@@ -38,7 +38,7 @@ const createUpdateNotifier = strapi => {
     config = new Configstore(
       pkg.name,
       {},
-      { configPath: path.join(strapi.dirs.root, '.strapi-updater.json') }
+      { configPath: path.join(strapi.dirs.app.root, '.strapi-updater.json') }
     );
   } catch {
     // we don't have write access to the file system