Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(javascript): update READMEs #3829

Merged
merged 9 commits into from
Sep 25, 2024
Merged

chore(javascript): update READMEs #3829

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
8fa195b
chore(javascript): update READMEs
shortcuts Sep 24, 2024
a6b5238
Merge branch 'main' into chore/javascript-readme
shortcuts Sep 24, 2024
7ab269c
fix: generator naming
shortcuts Sep 24, 2024
86723a4
chore: algoliasearch sub clients notice
shortcuts Sep 24, 2024
ff7d85d
chore: pnpm
shortcuts Sep 24, 2024
bb5337d
chore: usage
shortcuts Sep 24, 2024
4ed4cc1
chore: add version
shortcuts Sep 24, 2024
56fe828
chore: typo
shortcuts Sep 24, 2024
7eb0d5f
chore: kebab case
shortcuts Sep 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions clients/algoliasearch-client-javascript/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,11 @@ Without a package manager
Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/algoliasearch/dist/algoliasearch.umd.min.js"></script>
// for the full client
<script src="https://cdn.jsdelivr.net/npm/algoliasearch/dist/algoliasearch.umd.js"></script>

// for the lite client
<script src="https://cdn.jsdelivr.net/npm/algoliasearch/dist/lite/builds/browser.umd.js"></script>
```

You can now import the Algolia API client in your project and play with it.
Expand All @@ -63,7 +67,7 @@ import { liteClient } from 'algoliasearch/lite';
const client = liteClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/)**.
For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/search/)**.

## ❓ Troubleshooting

Expand Down
18 changes: 14 additions & 4 deletions generators/src/main/java/com/algolia/codegen/AlgoliaJavascriptGenerator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,14 +148,23 @@ public static String getPackageName(String client) throws ConfigException {

/** Set default generator options */
private void setDefaultGeneratorOptions() {
String apiName = CLIENT + Helpers.API_SUFFIX;
String clientName = CLIENT + Helpers.API_SUFFIX;
String packageName = getPackageName((String) additionalProperties.get("client"));

additionalProperties.put("apiName", apiName);
additionalProperties.put("apiName", CLIENT);
additionalProperties.put("clientName", clientName);
additionalProperties.put("algoliaAgent", Helpers.capitalize(CLIENT));
additionalProperties.put("isSearchClient", CLIENT.equals("search") || isAlgoliasearchClient);
additionalProperties.put("isIngestionClient", CLIENT.equals("ingestion"));
additionalProperties.put("isAlgoliasearchClient", isAlgoliasearchClient);
additionalProperties.put(
"isAvailableInAlgoliasearch",
CLIENT.equals("search") ||
CLIENT.equals("recommend") ||
CLIENT.equals("personalization") ||
CLIENT.equals("analytics") ||
CLIENT.equals("abtesting")
);
additionalProperties.put("packageVersion", Helpers.getPackageJsonVersion(packageName));
additionalProperties.put("packageName", packageName);
additionalProperties.put("npmPackageName", isAlgoliasearchClient ? packageName : "@algolia/" + packageName);
Expand All @@ -170,8 +179,9 @@ private void setDefaultGeneratorOptions() {
additionalProperties.put("recommendVersion", Helpers.getPackageJsonVersion("recommend"));

// Files used to generate the `lite` client
apiName = "lite" + Helpers.API_SUFFIX;
additionalProperties.put("apiName", apiName);
clientName = "lite" + Helpers.API_SUFFIX;
additionalProperties.put("apiName", "search");
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is apiName still used ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yup just for the link to the doc

additionalProperties.put("clientName", clientName);
additionalProperties.put("algoliaAgent", "Lite");
}
}
Expand Down
40 changes: 30 additions & 10 deletions templates/javascript/clients/README.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,45 +32,65 @@

## 💡 Getting Started

To get started, you first need to install {{npmPackageName}} (or any other available API client package).
{{#isAvailableInAlgoliasearch}}
> [!TIP]
> This API client already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `{{{npmPackageName}}}` if you already have `algoliasearch` installed.
shortcuts marked this conversation as resolved.
Show resolved Hide resolved
{{/isAvailableInAlgoliasearch}}

To get started, you first need to install {{npmPackageName}} (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager


```bash
yarn add {{npmPackageName}}
yarn add {{npmPackageName}}@{{{packageVersion}}}
# or
npm install {{npmPackageName}}@{{{packageVersion}}}
# or
npm install {{npmPackageName}}
pnpm add {{npmPackageName}}@{{{packageVersion}}}
```

Without a package manager
### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/algoliasearch/dist/{{packageName}}.umd.min.js"></script>
{{#isAlgoliasearchClient}}
// for the full client
<script src="https://cdn.jsdelivr.net/npm/algoliasearch@{{{packageVersion}}}/dist/algoliasearch.umd.js"></script>

// for the lite client
<script src="https://cdn.jsdelivr.net/npm/algoliasearch@{{{packageVersion}}}/dist/lite/builds/browser.umd.js"></script>
{{/isAlgoliasearchClient}}
{{^isAlgoliasearchClient}}
<script src="https://cdn.jsdelivr.net/npm/{{{npmPackageName}}}@{{{packageVersion}}}/dist/builds/browser.umd.js"></script>
{{/isAlgoliasearchClient}}
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
{{^isAlgoliasearchClient}}
import { {{apiName}} } from '{{npmPackageName}}';
import { {{clientName}} } from '{{npmPackageName}}';

const client = {{apiName}}('YOUR_APP_ID', 'YOUR_API_KEY');
const client = {{clientName}}('YOUR_APP_ID', 'YOUR_API_KEY');
{{/isAlgoliasearchClient}}
{{#isAlgoliasearchClient}}
import { algoliasearch } from '{{npmPackageName}}';

const client = algoliasearch('YOUR_APP_ID', 'YOUR_API_KEY');

// or with the lite client
import { {{apiName}} } from '{{npmPackageName}}/lite';
import { {{clientName}} } from '{{npmPackageName}}/lite';

const client = {{apiName}}('YOUR_APP_ID', 'YOUR_API_KEY');
const client = {{clientName}}('YOUR_APP_ID', 'YOUR_API_KEY');
{{/isAlgoliasearchClient}}
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/)**.
For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/{{apiName}}/)**.

## ❓ Troubleshooting

Expand Down
2 changes: 1 addition & 1 deletion templates/javascript/clients/api-single.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ export const apiClientVersion = '{{packageVersion}}';
{{/isIngestionClient}}

// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
export function create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({
export function create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({
appId: appIdOption,
apiKey: apiKeyOption,
authMode,
Expand Down
4 changes: 2 additions & 2 deletions templates/javascript/clients/client/builds/browser.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
// {{{generationBanner}}}

export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}>;
export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}>;

{{> client/builds/definition}}
return create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({
return create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({
appId,
apiKey,{{#hasRegionalHost}}region,{{/hasRegionalHost}}
timeouts: {
Expand Down
10 changes: 5 additions & 5 deletions templates/javascript/clients/client/builds/definition.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@ import { createHttpRequester } from '@algolia/requester-node-http';
import { createFetchRequester } from '@algolia/requester-fetch';
import { createNullLogger, createMemoryCache, createFallbackableCache, createBrowserLocalStorageCache, createNullCache, ClientOptions, serializeQueryParameters, DEFAULT_CONNECT_TIMEOUT_NODE, DEFAULT_READ_TIMEOUT_NODE, DEFAULT_WRITE_TIMEOUT_NODE, DEFAULT_CONNECT_TIMEOUT_BROWSER, DEFAULT_READ_TIMEOUT_BROWSER, DEFAULT_WRITE_TIMEOUT_BROWSER } from '@algolia/client-common';

import { create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}, apiClientVersion } from '../src/{{apiName}}';
import { create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}, apiClientVersion } from '../src/{{clientName}}';

{{#hasRegionalHost}}
import { Region, REGIONS } from '../src/{{apiName}}';
import { Region, REGIONS } from '../src/{{clientName}}';
{{/hasRegionalHost}}

{{! We don't use `export *` to prevent exposing the factory, to avoid confusion for the user }}
Expand All @@ -20,7 +20,7 @@ export {
isScheduleTrigger,
isSubscriptionTrigger,
{{/isIngestionClient}}
} from '../src/{{apiName}}';
} from '../src/{{clientName}}';
export * from '../model';

{{#isSearchClient}}
Expand All @@ -32,11 +32,11 @@ import {createHmac} from 'node:crypto';
{{/nodeSearchHelpers}}

// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
export function {{apiName}}(
export function {{clientName}}(
appId: string,
apiKey: string,{{#hasRegionalHost}}region{{#fallbackToAliasHost}}?{{/fallbackToAliasHost}}: Region,{{/hasRegionalHost}}
options?: ClientOptions
): {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} {
): {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} {
if (!appId || typeof appId !== 'string') {
throw new Error("`appId` is missing.");
}
Expand Down
4 changes: 2 additions & 2 deletions templates/javascript/clients/client/builds/fetch.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
// {{{generationBanner}}}

export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}>{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}};
export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}>{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}};

{{> client/builds/definition}}
return {
...create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({
...create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({
appId,
apiKey,{{#hasRegionalHost}}region,{{/hasRegionalHost}}
timeouts: {
Expand Down
4 changes: 2 additions & 2 deletions templates/javascript/clients/client/builds/liteNode.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
// {{{generationBanner}}}

export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}>;
export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}>;

{{> client/builds/definition}}
return create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({
return create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({
appId,
apiKey,{{#hasRegionalHost}}region,{{/hasRegionalHost}}
timeouts: {
Expand Down
4 changes: 2 additions & 2 deletions templates/javascript/clients/client/builds/node.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
// {{{generationBanner}}}

export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}>{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}};
export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}>{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}};

{{> client/builds/definition}}
return {
...create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({
...create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({
appId,
apiKey,{{#hasRegionalHost}}region,{{/hasRegionalHost}}
timeouts: {
Expand Down
2 changes: 1 addition & 1 deletion templates/javascript/clients/rollup.config.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ export default [
['lite']: 'lite',
{{/isAlgoliasearchClient}}
{{^isAlgoliasearchClient}}
['{{apiName}}']: '{{apiName}}',
['{{clientName}}']: '{{clientName}}',
{{/isAlgoliasearchClient}}
},
},
Expand Down
2 changes: 1 addition & 1 deletion templates/javascript/clients/tsup.config.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ const nodeConfigs: Options[] = [
const browserOptions: Options = {
...getBaseBrowserOptions(pkg, __dirname),
{{^isAlgoliasearchClient}}
globalName: '{{apiName}}',
globalName: '{{clientName}}',
{{/isAlgoliasearchClient}}
{{#isAlgoliasearchClient}}
globalName: 'lite',
Expand Down
2 changes: 1 addition & 1 deletion templates/kotlin/README.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ var response = client.search(
println(response)
```

For full documentation, visit the **[Algolia Kotlin API Client](https://www.algolia.com/doc/libraries/kotlin/)**.
For full documentation, visit the **[Algolia Kotlin API Client](https://www.algolia.com/doc/libraries/kotlin/v3/)**.

## ❓ Troubleshooting

Expand Down
Loading