1 | import { ErrorLike } from './errors';
|
2 | import * as GQL from './schema/graphqlschema';
|
3 | export declare type ID = string;
|
4 | export interface IClient {
|
5 | __typename: 'Client';
|
6 | displayName: string;
|
7 | }
|
8 | /**
|
9 | * A subset of the settings JSON Schema type containing the minimum needed by this library.
|
10 | */
|
11 | export interface Settings {
|
12 | extensions?: {
|
13 | [extensionID: string]: boolean;
|
14 | };
|
15 | [key: string]: any;
|
16 | subjects?: never;
|
17 | merged?: never;
|
18 | }
|
19 | /**
|
20 | * A configuration subject is something that can have settings associated with it, such as a site ("global
|
21 | * settings"), an organization ("organization settings"), a user ("user settings"), etc.
|
22 | */
|
23 | export declare type ConfigurationSubject = Pick<GQL.IConfigurationSubject, 'id' | 'settingsURL' | 'viewerCanAdminister'> & (Pick<IClient, '__typename' | 'displayName'> | Pick<GQL.IUser, '__typename' | 'username' | 'displayName'> | Pick<GQL.IOrg, '__typename' | 'name' | 'displayName'> | Pick<GQL.ISite, '__typename'>);
|
24 | /**
|
25 | * A cascade of settings from multiple subjects, from lowest precedence to highest precedence, and the final
|
26 | * settings, merged in order of precedence from the settings for each subject in the cascade.
|
27 | *
|
28 | * Callers that need to represent the null/error states should use {@link ConfigurationCascade}.
|
29 | *
|
30 | * @template S the configuration subject type
|
31 | * @template C the settings type
|
32 | */
|
33 | export interface ConfigurationCascade<S extends ConfigurationSubject, C extends Settings = Settings> {
|
34 | /**
|
35 | * The settings for each subject in the cascade, from lowest to highest precedence.
|
36 | */
|
37 | subjects: ConfiguredSubject<S, C>[];
|
38 | merged: C;
|
39 | }
|
40 | /**
|
41 | * A configuration cascade that also supports representing subjects with no settings or whose settings triggered an
|
42 | * error.
|
43 | *
|
44 | * Callers that don't need to represent the null/error states should use {@link ConfigurationCascade}.
|
45 | *
|
46 | * @template S the configuration subject type
|
47 | * @template C the settings type
|
48 | */
|
49 | export interface ConfigurationCascadeOrError<S extends ConfigurationSubject, C extends Settings = Settings> extends Pick<ConfigurationCascade<S, C>, Exclude<keyof ConfigurationCascade<S, C>, 'subjects' | 'merged'>> {
|
50 | /**
|
51 | * The settings for each subject in the cascade, from lowest to highest precedence, null if there are none, or
|
52 | * an error.
|
53 | *
|
54 | * @see ConfigurationCascade#subjects
|
55 | */
|
56 | subjects: ConfiguredSubjectOrError<S, C>[] | ErrorLike | null;
|
57 | /**
|
58 | * The final settings (merged in order of precedence from the settings for each subject in the cascade), an
|
59 | * error (if any occurred while retrieving, parsing, or merging the settings), or null if there are no settings
|
60 | * from any of the subjects.
|
61 | *
|
62 | * @see ConfigurationCascade#merged
|
63 | */
|
64 | merged: C | ErrorLike | null;
|
65 | }
|
66 | /**
|
67 | * A subject and its settings.
|
68 | *
|
69 | * Callers that need to represent the null/error states should use {@link ConfiguredSubjectOrError}.
|
70 | *
|
71 | * @template S the configuration subject type
|
72 | * @template C the settings type
|
73 | */
|
74 | export interface ConfiguredSubject<S extends ConfigurationSubject, C extends Settings = Settings> {
|
75 | /** The subject. */
|
76 | subject: S;
|
77 | /** The subject's settings. */
|
78 | settings: C;
|
79 | }
|
80 | /**
|
81 | * A subject and its settings, or null if there are no settings, or an error.
|
82 | *
|
83 | * Callers that don't need to represent the null/error states should use {@link ConfiguredSubject}.
|
84 | */
|
85 | export interface ConfiguredSubjectOrError<S extends ConfigurationSubject, C extends Settings = Settings> extends Pick<ConfiguredSubject<S, C>, Exclude<keyof ConfiguredSubject<S, C>, 'settings'>> {
|
86 | /**
|
87 | * The subject's settings (if any), an error (if any occurred while retrieving or parsing the settings), or
|
88 | * null if there are no settings.
|
89 | */
|
90 | settings: C | ErrorLike | null;
|
91 | }
|
92 | /** A minimal subset of a GraphQL ConfigurationSubject type that includes only the single contents value. */
|
93 | export interface SubjectConfigurationContents {
|
94 | latestSettings: {
|
95 | configuration: {
|
96 | contents: string;
|
97 | };
|
98 | } | null;
|
99 | }
|
100 | /** Converts a GraphQL ConfigurationCascade value to a value of this library's ConfigurationCascade type. */
|
101 | export declare function gqlToCascade<S extends ConfigurationSubject, C extends Settings>({ subjects, }: {
|
102 | subjects: (S & SubjectConfigurationContents)[];
|
103 | }): ConfigurationCascadeOrError<S, C>;
|
104 | /**
|
105 | * Deeply merges the settings without modifying any of the input values. The array is ordered from lowest to
|
106 | * highest precedence in the merge.
|
107 | *
|
108 | * TODO(sqs): In the future, this will pass a CustomMergeFunctions value to merge.
|
109 | */
|
110 | export declare function mergeSettings<C extends Settings>(values: C[]): C | null;
|
111 | export interface CustomMergeFunctions {
|
112 | [key: string]: (base: any, add: any) => any | CustomMergeFunctions;
|
113 | }
|
114 | /**
|
115 | * Deeply merges add into base (modifying base). The merged value for a key path can be customized by providing a
|
116 | * function at the same key path in custom.
|
117 | *
|
118 | * Most callers should use mergeSettings, which uses the set of CustomMergeFunctions that are required to properly
|
119 | * merge settings.
|
120 | */
|
121 | export declare function merge(base: any, add: any, custom?: CustomMergeFunctions): void;
|
122 | /**
|
123 | * The conventional ordering of extension configuration subject types in a list.
|
124 | */
|
125 | export declare const SUBJECT_TYPE_ORDER: ConfigurationSubject['__typename'][];
|
126 | export declare function subjectTypeHeader(nodeType: ConfigurationSubject['__typename']): string | null;
|
127 | export declare function subjectLabel(subject: ConfigurationSubject): string;
|
128 | /**
|
129 | * React partial props for components needing the configuration cascade.
|
130 | */
|
131 | export interface ConfigurationCascadeProps<S extends ConfigurationSubject, C extends Settings> {
|
132 | configurationCascade: ConfigurationCascadeOrError<S, C>;
|
133 | }
|